/ Hex Artifact Content
Login

Artifact 66f0884d0a6e84babf3a9f3be6c1ca3e94711356:


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 33 20 32 30 30 39 2f 30  n,v 1.453 2009/0
05f0: 35 2f 32 34 20 31 31 3a 30 37 3a 34 39 20 64 72  5/24 11:07:49 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 3c 2f 64  cation needs.</d
c230: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c240: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c250: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c260: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
c270: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c280: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
c290: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
c2a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
c2b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c2c0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c2d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
c2e0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
c2f0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
c300: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
c310: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c320: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
c330: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
c340: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
c350: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c360: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
c370: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  EX</dt>.** <dd>T
c380: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c390: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c3a0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c3b0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
c3c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
c3d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c3e0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
c3f0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
c400: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
c410: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
c420: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
c430: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
c440: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
c450: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  es..** This opti
c460: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
c470: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
c480: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
c490: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
c4a0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
c4b0: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
c4c0: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
c4d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
c4e0: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
c4f0: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
c500: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
c510: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c520: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
c530: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c540: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
c550: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
c560: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
c570: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61  .** memory allca
c580: 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f  tion lookaside o
c590: 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68  ptimization.  Th
c5a0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c5b0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
c5c0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
c5d0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
c5e0: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
c5f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
c600: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
c610: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
c620: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64  e connection.</d
c630: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c640: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
c650: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c660: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c670: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c680: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c690: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
c6a0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
c6b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
c6c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
c6d0: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
c6e0: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
c6f0: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
c700: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53  plementation.  S
c710: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
c720: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
c730: 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
c740: 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
c750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c760: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c770: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c780: 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  GETPCACHE</dt>.*
c790: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c7a0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c7b0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c7c0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c7d0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
c7e0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
c7f0: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
c800: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
c810: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
c820: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c830: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
c840: 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ct.</dd>.**.** <
c850: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
c860: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c870: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
c880: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
c890: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
c8a0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
c8b0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c8c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c8d0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
c8e0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
c8f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c900: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
c910: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
c920: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c940: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
c950: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
c960: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
c970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c980: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
c990: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
c9a0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
c9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c9c0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c9d0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
c9e0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
c9f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ca00: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
ca10: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
ca20: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
ca30: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
ca40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ca50: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
ca60: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
ca70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ca80: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
ca90: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
caa0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
cab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cac0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
cad0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
cae0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
caf0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
cb00: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
cb10: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
cb20: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
cb30: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
cb40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cb50: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
cb60: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
cb70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cb80: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
cb90: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
cba0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
cbb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cbc0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
cbd0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
cbe0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
cbf0: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  hods* */../*.** 
cc00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
cc10: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  uration Options 
cc20: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30  {H10170} <S20000
cc30: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
cc40: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  L.**.** These co
cc50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
cc60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
cc70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
cc80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
cc90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
cca0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ccb0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ccc0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ccd0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
cce0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
ccf0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
cd00: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
cd10: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
cd20: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
cd30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
cd40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
cd50: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
cd60: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
cd70: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
cd80: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
cd90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
cda0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
cdb0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
cdc0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
cdd0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
cde0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
cdf0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
ce00: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
ce10: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
ce20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
ce30: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
ce40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ce50: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
ce60: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
ce70: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
ce80: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
ce90: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
cea0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
ceb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
cec0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
ced0: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
cee0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
cef0: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
cf00: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
cf10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cf20: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
cf30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
cf40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
cf50: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
cf60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
cf70: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
cf80: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
cf90: 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
cfa0: 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20  de memory.  The 
cfb0: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
cfc0: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  t may be NULL in
cfd0: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
cfe0: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
cff0: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
d000: 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  * buffer itself 
d010: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d020: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73  alloc()].  The s
d030: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
d040: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
d050: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
d060: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
d070: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
d080: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
d090: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
d0a0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
d0b0: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
d0c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
d0d0: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
d0e0: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
d0f0: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
d100: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
d110: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f  ird arguments.</
d120: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d140: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
d150: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
d160: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
d170: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
d180: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
d190: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
d1a0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
d1b0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
d1c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d1d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d1e0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
d1f0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
d200: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
d210: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d220: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
d230: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
d240: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
d250: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
d260: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
d270: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
d280: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d290: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
d2a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
d2b0: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
d2c0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d2d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d2e0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
d2f0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
d300: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
d310: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
d320: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
d330: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
d340: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
d350: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
d360: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
d370: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
d380: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
d390: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
d3a0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
d3b0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
d3c0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
d3d0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
d3e0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
d3f0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
d400: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
d410: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
d420: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
d430: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
d440: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
d450: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
d460: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
d470: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
d480: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
d490: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
d4a0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
d4b0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
d4c0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
d4d0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
d4e0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
d4f0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
d500: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
d510: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
d520: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
d530: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
d540: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
d550: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
d560: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
d570: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
d580: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
d590: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
d5a0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
d5b0: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
d5c0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
d5d0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
d5e0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
d5f0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
d600: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
d610: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
d620: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
d630: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
d640: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
d650: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
d660: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
d670: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
d680: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
d690: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
d6a0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
d6b0: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
d6c0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
d6d0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
d6e0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
d6f0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
d700: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
d710: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
d720: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
d730: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
d740: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d750: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
d760: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
d770: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
d780: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
d790: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
d7a0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
d7b0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
d7c0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
d7d0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
d7e0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
d7f0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
d800: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
d810: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
d820: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
d830: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
d840: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
d850: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
d860: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
d870: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
d880: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
d890: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
d8a0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
d8b0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
d8c0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
d8d0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
d8e0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
d8f0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
d900: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
d910: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
d920: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
d930: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
d940: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
d950: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
d960: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
d970: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
d980: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
d990: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
d9a0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
d9b0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
d9c0: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
d9d0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
d9e0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
d9f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
da00: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
da10: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
da20: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
da30: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
da40: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
da50: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
da60: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
da70: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
da80: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
da90: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
daa0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
dab0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
dac0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
dad0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
dae0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
daf0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
db00: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
db10: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
db20: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
db30: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
db40: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
db50: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
db60: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
db70: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
db80: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
db90: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
dba0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
dbb0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
dbc0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
dbd0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
dbe0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
dbf0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
dc00: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
dc10: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
dc20: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
dc30: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
dc40: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
dc50: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
dc60: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
dc70: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
dc80: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
dc90: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
dca0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
dcb0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
dcc0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
dcd0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
dce0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
dcf0: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
dd00: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
dd10: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
dd20: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
dd30: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
dd40: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
dd50: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
dd60: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
dd70: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
dd80: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
dd90: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
dda0: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
ddb0: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
ddc0: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
ddd0: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
dde0: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
ddf0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
de00: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
de10: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
de20: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
de30: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
de40: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
de50: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
de60: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
de70: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
de80: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
de90: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
dea0: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
deb0: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
dec0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
ded0: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
dee0: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
def0: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
df00: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
df10: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
df20: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
df30: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
df40: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
df50: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
df60: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
df70: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
df80: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
df90: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
dfa0: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
dfb0: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
dfc0: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
dfd0: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
dfe0: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
dff0: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
e000: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
e010: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
e020: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
e030: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
e040: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
e050: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
e060: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
e070: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
e080: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
e090: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
e0a0: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
e0b0: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
e0c0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
e0d0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
e0e0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
e0f0: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
e100: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
e110: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
e120: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
e130: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
e140: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
e150: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
e160: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
e170: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e180: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e190: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
e1a0: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
e1b0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
e1c0: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
e1d0: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
e1e0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
e1f0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
e200: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
e210: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
e220: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
e230: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
e240: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
e250: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
e260: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
e270: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
e280: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
e290: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
e2a0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
e2b0: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
e2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
e2d0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
e2e0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
e2f0: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
e300: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e310: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
e320: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
e330: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
e340: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
e350: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
e360: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
e370: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
e380: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
e390: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
e3a0: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
e3b0: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
e3c0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
e3d0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e3e0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
e3f0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
e400: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
e410: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
e420: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34  ments:.** [H1224
e430: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a  1] [H12243].**.*
e440: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e450: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e460: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e470: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e480: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e490: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e4a0: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
e4b0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
e4c0: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
e4d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
e4e0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
e4f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
e500: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
e510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e520: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
e530: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
e540: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
e550: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
e560: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
e570: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
e580: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e590: 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
e5a0: 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
e5b0: 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
e5c0: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
e5d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
e5e0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
e5f0: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
e600: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
e610: 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20  all .** [CREATE 
e620: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
e630: 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  r] contexts.  Ho
e640: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
e650: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
e660: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
e670: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
e680: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
e690: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
e6a0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e6b0: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
e6c0: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
e6d0: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
e6e0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
e6f0: 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
e700: 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
e710: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
e720: 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
e730: 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
e740: 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
e750: 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
e760: 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
e770: 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
e780: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ed..** The chang
e790: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
e7a0: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
e7b0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
e7c0: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
e7d0: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
e7e0: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
e7f0: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
e800: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
e810: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
e820: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
e830: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
e840: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
e850: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
e860: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
e870: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
e880: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
e890: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
e8a0: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
e8b0: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e8c0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e8d0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e8e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e8f0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e900: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e910: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
e920: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
e930: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
e940: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e950: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
e960: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
e970: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e980: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
e990: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
e9a0: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
e9b0: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
e9c0: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
e9d0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e9e0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
e9f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
ea00: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
ea10: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
ea20: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
ea30: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
ea40: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
ea50: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
ea60: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
ea70: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
ea80: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
ea90: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
eaa0: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
eab0: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
eac0: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
ead0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
eae0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
eaf0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
eb00: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
eb10: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
eb20: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
eb30: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
eb40: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
eb50: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
eb60: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
eb70: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
eb80: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
eb90: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
eba0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ebb0: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
ebc0: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
ebd0: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
ebe0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ebf0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
ec00: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
ec10: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
ec20: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
ec30: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
ec40: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ec50: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
ec60: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ec70: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ec80: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ec90: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
eca0: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ecb0: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
ecc0: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ecd0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ece0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ecf0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ed00: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
ed10: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
ed20: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
ed30: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ed40: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
ed50: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
ed60: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
ed70: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
ed80: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
ed90: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
eda0: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
edb0: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ally..**.** The 
edc0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
edd0: 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
ede0: 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
edf0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
ee00: 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
ee10: 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
ee20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
ee30: 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e  complete.  Any n
ee40: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
ee50: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ee60: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
ee70: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ee80: 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
ee90: 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
eea0: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
eeb0: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
eec0: 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
eed0: 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
eee0: 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
eef0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
ef00: 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
ef10: 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65  .  New SQL state
ef20: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
ef30: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
ef40: 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
ef50: 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
ef60: 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
ef70: 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
ef80: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
ef90: 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61  rrupt()..** A ca
efa0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
efb0: 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
efc0: 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
efd0: 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
efe0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
eff0: 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
f000: 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
f010: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
f020: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
f030: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
f040: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f050: 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
f060: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
f070: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31  ents:.** [H12271
f080: 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a  ] [H12272].**.**
f090: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
f0a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
f0b0: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
f0c0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
f0d0: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
f0e0: 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
f0f0: 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
f100: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
f110: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
f120: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
f130: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
f140: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
f150: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
f160: 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30   {H10510} <S7020
f170: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
f180: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
f190: 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
f1a0: 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
f1b0: 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
f1c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
f1d0: 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
f1e0: 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
f1f0: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
f200: 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
f210: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
f220: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
f230: 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
f240: 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
f250: 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
f260: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
f270: 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
f280: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
f290: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
f2a0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
f2b0: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
f2c0: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
f2d0: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
f2e0: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
f2f0: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
f300: 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
f310: 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
f320: 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
f330: 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
f340: 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
f350: 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
f360: 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
f370: 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
f380: 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
f390: 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
f3a0: 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
f3b0: 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
f3c0: 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
f3d0: 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
f3e0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
f3f0: 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
f400: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
f410: 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
f420: 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70  inator.  Whitesp
f430: 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
f440: 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
f450: 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
f460: 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
f470: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f480: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
f490: 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
f4a0: 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
f4b0: 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
f4c0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
f4d0: 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
f4e0: 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
f4f0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f500: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
f510: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
f520: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
f530: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
f540: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
f550: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
f560: 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
f570: 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
f580: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
f590: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f5a0: 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
f5b0: 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
f5c0: 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
f5d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f5e0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f5f0: 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
f600: 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
f610: 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
f620: 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
f630: 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
f640: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
f650: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
f660: 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
f670: 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
f680: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
f690: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
f6a0: 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
f6b0: 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  mplete..**.** Re
f6c0: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
f6d0: 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a  511] [H10512].**
f6e0: 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
f6f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
f700: 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
f710: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
f720: 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
f730: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
f740: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
f750: 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
f760: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
f770: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
f780: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
f790: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
f7a0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
f7b0: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
f7c0: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
f7d0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
f7e0: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
f7f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f800: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
f810: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
f820: 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
f830: 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
f840: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
f850: 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
f860: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
f870: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
f880: 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
f890: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
f8a0: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
f8b0: 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
f8c0: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
f8d0: 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
f8e0: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
f8f0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
f900: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
f910: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
f920: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
f930: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
f940: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
f950: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
f960: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
f970: 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
f980: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
f990: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
f9a0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
f9b0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
f9c0: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
f9d0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
f9e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
f9f0: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
fa00: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
fa10: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
fa20: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
fa30: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
fa40: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
fa50: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fa60: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
fa70: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
fa80: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
fa90: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
faa0: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
fab0: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
fac0: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
fad0: 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
fae0: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
faf0: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
fb00: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
fb10: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
fb20: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
fb30: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
fb40: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
fb50: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
fb60: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
fb70: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
fb80: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
fb90: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
fba0: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
fbb0: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
fbc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
fbd0: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
fbe0: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
fbf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
fc00: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
fc10: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
fc20: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
fc30: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
fc40: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
fc50: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
fc60: 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
fc70: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
fc80: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
fc90: 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
fca0: 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
fcb0: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
fcc0: 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
fcd0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
fce0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
fcf0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
fd00: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
fd10: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fd20: 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
fd30: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
fd40: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
fd50: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
fd60: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
fd70: 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
fd80: 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
fd90: 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
fda0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
fdb0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
fdc0: 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
fdd0: 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
fde0: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
fdf0: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
fe00: 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
fe10: 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
fe20: 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
fe30: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
fe40: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
fe50: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
fe60: 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
fe70: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
fe80: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
fe90: 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
fea0: 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
feb0: 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
fec0: 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
fed0: 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
fee0: 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
fef0: 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
ff00: 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
ff10: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
ff20: 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
ff30: 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
ff40: 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
ff50: 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
ff60: 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
ff70: 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
ff80: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
ff90: 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
ffa0: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
ffb0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
ffc0: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
ffd0: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
ffe0: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
fff0: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
10000 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
10010 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
10020 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
10030 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
10040 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
10050 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
10060 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
10070 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
10080 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
10090 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
100a0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
100b0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
100c0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
100d0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
100e0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
100f0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
10100 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
10110 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
10120 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
10130 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
10140 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
10150 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
10160 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
10170 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
10180 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
10190 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
101a0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
101b0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
101c0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
101d0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
101e0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
101f0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
10200 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
10210 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
10220 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
10230 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
10240 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
10250 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
10260 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
10270 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
10280 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
10290 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
102a0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
102b0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
102c0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
102d0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
102e0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
102f0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
10300 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
10310 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
10320 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
10330 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
10340 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
10350 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
10360 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
10370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10380 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
10390 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
103a0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
103b0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
103c0 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
103d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
103e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
103f0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
10400 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
10410 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
10420 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
10430 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
10440 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
10450 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
10460 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
10470 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
10480 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
10490 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
104a0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
104b0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
104c0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
104d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
104e0 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32  ** [H12311] [H12
104f0 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48  312] [H12314] [H
10500 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a  12316] [H12318].
10510 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  **.** A busy han
10520 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
10530 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
10540 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
10550 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
10560 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
10570 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
10580 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
10590 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
105a0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
105b0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
105c0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
105d0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
105e0 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33  sy Timeout {H123
105f0 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  40} <S40410>.**.
10600 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10610 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
10620 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
10630 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
10640 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
10650 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
10660 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
10670 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
10680 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
10690 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
106a0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
106b0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
106c0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
106d0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
106e0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
106f0 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  H12343} After "m
10700 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
10710 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
10720 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
10730 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
10740 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
10750 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
10760 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10770 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10780 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
10790 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
107a0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
107b0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
107c0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
107d0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
107e0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
107f0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
10800 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
10810 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
10820 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
10830 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10840 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
10850 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
10860 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
10870 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
10880 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
10890 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
108a0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
108b0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
108c0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
108d0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
108e0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
108f0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10900 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b  s:.** [H12341] [
10910 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d  H12343] [H12344]
10920 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10930 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
10940 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
10950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10960 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
10970 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
10980 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37  g Queries {H1237
10990 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
109a0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
109b0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
109c0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
109d0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
109e0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
109f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10a00 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
10a10 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10a20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
10a30 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
10a40 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
10a50 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
10a60 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
10a70 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
10a80 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
10a90 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
10aa0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
10ab0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
10ac0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
10ad0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
10ae0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
10af0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
10b00 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
10b10 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10b20 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
10b30 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
10b40 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
10b50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
10b60 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
10b70 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
10b80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
10b90 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
10ba0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
10bb0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
10bc0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
10bd0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
10be0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
10bf0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
10c00 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
10c10 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
10c20 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
10c30 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
10c40 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
10c50 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
10c60 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
10c70 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
10c80 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
10c90 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
10ca0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
10cb0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
10cc0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
10cd0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
10ce0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
10cf0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
10d00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
10d10 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
10d20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
10d30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
10d40 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
10d50 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
10d60 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
10d70 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
10d80 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
10d90 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
10da0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
10db0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
10dc0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
10dd0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
10de0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
10df0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
10e00 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
10e10 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
10e20 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
10e30 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
10e40 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
10e50 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
10e60 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
10e70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
10e80 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
10e90 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
10ea0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
10eb0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
10ec0 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
10ed0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
10ee0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
10ef0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
10f00 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
10f10 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
10f20 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
10f30 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
10f40 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
10f50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10f60 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
10f70 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
10f80 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
10f90 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
10fa0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
10fb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
10fc0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
10fd0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
10fe0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
10ff0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
11000 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
11010 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11020 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
11030 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11040 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
11050 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11060 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
11070 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
11080 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
11090 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
110a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
110b0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
110c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
110d0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
110e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
110f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
11100 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11110 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
11120 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
11130 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
11140 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
11150 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
11160 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
11170 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
11180 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
11190 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
111a0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
111b0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
111c0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
111d0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
111e0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
111f0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
11200 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
11210 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
11220 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
11230 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
11240 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11250 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
11260 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
11270 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
11280 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
11290 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
112a0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
112b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
112c0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
112d0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
112e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
112f0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
11300 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
11310 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
11320 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
11330 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
11340 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
11350 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
11360 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
11370 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
11380 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
11390 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
113a0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
113b0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
113c0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
113d0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
113e0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
113f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11400 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
11410 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
11420 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
11430 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
11440 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
11450 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
11460 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
11470 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
11480 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
11490 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
114a0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
114b0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
114c0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
114d0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
114e0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
114f0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
11500 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
11510 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
11520 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
11530 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
11540 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
11550 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33  ements:.** [H123
11560 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31  71] [H12373] [H1
11570 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b  2374] [H12376] [
11580 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d  H12379] [H12382]
11590 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
115a0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
115b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
115c0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
115d0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
115e0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
115f0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
11600 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
11610 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
11620 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
11630 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
11640 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
11650 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
11660 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
11670 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11680 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
11690 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
116a0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
116b0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
116c0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
116d0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
116e0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
116f0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
11700 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
11710 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
11720 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
11730 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
11740 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
11750 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
11760 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
11770 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
11780 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
11790 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
117a0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
117b0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
117c0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
117d0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
117e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
117f0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
11800 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
11810 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
11820 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
11830 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
11840 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
11850 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
11860 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
11870 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
11880 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
11890 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
118a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
118b0 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75  ee()].  Both rou
118c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
118d0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
118e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
118f0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
11900 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
11910 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
11920 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
11930 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
11940 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
11950 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
11960 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
11970 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
11980 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
11990 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
119a0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
119b0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
119c0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
119d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
119e0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
119f0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
11a00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11a10 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
11a20 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
11a30 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
11a40 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
11a50 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
11a60 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
11a70 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
11a80 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
11a90 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
11aa0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
11ab0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
11ac0 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
11ad0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
11ae0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
11af0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
11b00 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
11b10 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
11b20 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
11b30 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
11b40 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
11b50 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
11b60 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
11b70 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
11b80 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
11b90 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
11ba0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
11bb0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
11bc0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
11bd0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
11be0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
11bf0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
11c00 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
11c10 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
11c20 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
11c30 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
11c40 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
11c50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
11c60 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
11c70 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
11c80 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
11c90 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
11ca0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
11cb0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
11cc0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
11cd0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
11ce0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
11cf0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
11d00 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
11d10 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
11d20 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
11d30 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
11d40 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
11d50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
11d60 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
11d70 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
11d80 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
11d90 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
11da0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
11db0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
11dc0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
11dd0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
11de0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
11df0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
11e00 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
11e10 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
11e20 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
11e30 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
11e40 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
11e50 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
11e60 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
11e70 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
11e80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
11e90 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
11ea0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
11eb0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
11ec0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
11ed0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
11ee0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
11ef0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
11f00 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
11f10 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
11f20 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
11f30 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
11f40 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
11f50 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
11f60 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
11f70 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
11f80 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
11f90 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
11fa0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
11fb0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
11fc0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
11fd0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
11fe0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
11ff0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
12000 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
12010 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12020 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
12030 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
12040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
12050 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
12060 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12070 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
12080 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
12090 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
120a0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
120b0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
120c0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
120d0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
120e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
120f0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
12100 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12110 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
12120 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
12130 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
12140 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
12150 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
12160 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
12170 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
12180 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
12190 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
121a0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
121b0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
121c0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
121d0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
121e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
121f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
12200 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
12210 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
12220 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
12230 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
12240 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
12250 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
12260 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
12270 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
12280 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
12290 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
122a0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
122b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
122c0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
122d0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
122e0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
122f0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
12300 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
12310 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
12320 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
12330 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
12340 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
12350 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51  al..**.** The %Q
12360 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
12370 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
12380 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
12390 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
123a0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
123b0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
123c0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
123d0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
123e0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
123f0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
12400 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
12410 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
12420 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
12430 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
12440 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
12450 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
12460 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  n.  So, for exam
12470 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
12480 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
12490 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
124a0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
124b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
124c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
124d0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
124e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
124f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12500 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
12510 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
12520 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
12530 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
12540 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
12550 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
12560 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
12570 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
12580 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
12590 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
125a0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
125b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
125c0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
125d0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
125e0 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
125f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
12600 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
12610 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
12620 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
12630 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
12640 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
12650 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
12660 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
12670 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
12680 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
12690 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b  s:.** [H17403] [
126a0 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d  H17406] [H17407]
126b0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
126c0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
126d0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
126e0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
126f0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
12700 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
12710 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12720 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
12730 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
12740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
12750 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
12760 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33   Subsystem {H173
12770 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  00} <S20000>.**.
12780 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
12790 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
127a0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
127b0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
127c0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
127d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
127e0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
127f0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
12800 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
12810 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
12820 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12830 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
12840 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
12850 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
12860 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
12870 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
12880 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
12890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
128a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
128b0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
128c0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
128d0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
128e0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
128f0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
12900 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
12910 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  er..** If sqlite
12920 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
12930 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
12940 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
12950 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
12960 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
12970 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72  ter.  If the par
12980 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
12990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
129a0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
129b0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
129c0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
129d0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
129e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ter..**.** Calli
129f0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
12a00 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
12a10 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
12a20 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
12a30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
12a40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12a50 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
12a60 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
12a70 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
12a80 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  sed.  The sqlite
12a90 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
12aa0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
12ab0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
12ac0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
12ad0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
12ae0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
12af0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
12b00 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
12b10 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
12b20 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
12b30 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
12b40 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
12b50 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
12b60 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
12b70 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
12b80 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
12b90 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
12ba0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
12bb0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
12bc0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
12bd0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
12be0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
12bf0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
12c00 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
12c10 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
12c20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
12c30 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
12c40 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
12c50 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
12c60 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
12c70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
12c80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
12c90 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
12ca0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
12cb0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
12cc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12cd0 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
12ce0 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
12cf0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
12d00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
12d10 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
12d20 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
12d30 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
12d40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
12d50 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
12d60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
12d70 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
12d80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
12d90 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
12da0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
12db0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
12dc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
12dd0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
12de0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12df0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
12e00 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
12e10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12e20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
12e30 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
12e40 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
12e50 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
12e60 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
12e70 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
12e80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
12e90 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
12ea0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12eb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
12ec0 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
12ed0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
12ee0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
12ef0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
12f00 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
12f10 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
12f20 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
12f30 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
12f40 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
12f50 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
12f60 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
12f70 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
12f80 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
12f90 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
12fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
12fb0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
12fc0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
12fd0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
12fe0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
12ff0 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
13000 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
13010 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
13020 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
13030 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
13040 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
13050 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
13060 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
13070 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
13080 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
13090 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
130a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
130b0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
130c0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
130d0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
130e0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
130f0 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
13100 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
13110 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13120 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
13130 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
13140 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
13150 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
13160 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
13170 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48  C library..** {H
13180 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
13190 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
131a0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
131b0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
131c0 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
131d0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
131e0 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
131f0 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
13200 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
13210 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
13220 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
13230 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
13240 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
13250 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
13260 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
13270 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
13280 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13290 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
132a0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
132b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
132c0 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
132d0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
132e0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
132f0 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13300 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
13310 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
13320 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
13330 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
13340 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
13350 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
13360 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
13370 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13380 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
13390 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
133a0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
133b0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
133c0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
133d0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
133e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
133f0 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
13400 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
13410 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
13420 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
13430 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
13440 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
13450 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
13460 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
13470 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
13480 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
13490 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
134a0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
134b0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
134c0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
134d0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
134e0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
134f0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
13500 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
13510 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
13520 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
13530 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
13540 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
13550 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
13560 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
13570 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
13580 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
13590 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33  * [H17303] [H173
135a0 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31  04] [H17305] [H1
135b0 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b  7306] [H17310] [
135c0 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d  H17312] [H17315]
135d0 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31   [H17318].** [H1
135e0 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b  7321] [H17322] [
135f0 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68  H17323].**.** Th
13600 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
13610 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
13620 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
13630 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
13640 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
13650 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
13660 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
13670 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
13680 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13690 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
136a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
136b0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
136c0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
136d0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
136e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
136f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
13700 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
13710 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
13720 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
13730 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
13740 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
13750 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
13760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
13770 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
13780 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
13790 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
137a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
137b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
137c0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
137d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
137e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
137f0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
13800 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
13810 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
13820 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
13830 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
13840 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
13850 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
13860 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
13870 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
13880 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
13890 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
138a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
138b0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
138c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
138d0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
138e0 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  m..**.** Require
138f0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37  ments:.** [H1737
13900 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37  1] [H17373] [H17
13910 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f  374] [H17375].*/
13920 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13930 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13940 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
13950 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
13960 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
13970 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
13980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13990 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
139a0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
139b0 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30   {H17390} <S2000
139c0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
139d0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
139e0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
139f0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
13a00 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
13a10 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
13a20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
13a30 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
13a40 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
13a50 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
13a60 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
13a70 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
13a80 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
13a90 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
13aa0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
13ab0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
13ac0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
13ad0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
13ae0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
13af0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
13b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
13b10 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
13b20 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
13b30 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
13b40 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
13b50 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
13b60 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
13b70 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
13b80 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
13b90 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
13ba0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
13bb0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
13bc0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
13bd0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
13be0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
13bf0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
13c00 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
13c10 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
13c20 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
13c30 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
13c40 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
13c50 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
13c60 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
13c70 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
13c80 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
13c90 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
13ca0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
13cb0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
13cc0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
13cd0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
13ce0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13cf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32  ents:.** [H17392
13d00 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ].*/.void sqlite
13d10 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
13d20 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
13d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13d40 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
13d50 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
13d60 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
13d70 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
13d80 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
13d90 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
13da0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
13db0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
13dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13dd0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
13de0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13df0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
13e00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13e10 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
13e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
13e30 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
13e40 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
13e50 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
13e60 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
13e70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
13e80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
13e90 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
13ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
13eb0 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
13ec0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
13ed0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
13ee0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
13ef0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
13f00 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
13f10 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
13f20 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
13f30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13f40 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
13f50 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
13f60 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
13f70 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
13f80 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
13f90 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
13fa0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
13fb0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
13fc0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
13fd0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
13fe0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
13ff0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
14000 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
14010 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
14020 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
14030 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
14040 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
14050 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14060 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
14070 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
14080 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
14090 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
140a0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
140b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
140c0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
140d0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
140e0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
140f0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
14100 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
14110 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
14120 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
14130 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
14140 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
14150 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
14160 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
14170 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
14180 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
14190 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
141a0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
141b0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
141c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
141d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
141e0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
141f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14200 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
14210 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
14220 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
14230 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
14240 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
14250 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
14260 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
14270 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
14280 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
14290 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
142a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
142b0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
142c0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
142d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
142e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
142f0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
14300 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  e. The second pa
14310 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
14320 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
14330 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
14340 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
14350 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
14360 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
14370 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
14380 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54  be authorized. T
14390 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
143a0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
143b0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
143c0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
143d0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
143e0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
143f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
14400 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
14410 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
14420 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rized..**.** If 
14430 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
14440 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
14450 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
14460 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
14470 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
14480 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
14490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
144a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
144b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
144c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
144d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
144e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
144f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
14500 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
14510 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
14520 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
14530 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
14540 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
14550 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
14560 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
14570 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
14580 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
14590 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
145a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69  ..** If the acti
145b0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
145c0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
145d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
145e0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
145f0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
14600 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
14610 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
14620 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
14630 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
14640 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
14650 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
14660 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
14670 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
14680 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
14690 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
146a0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
146b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
146c0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
146d0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
146e0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
146f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
14700 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
14710 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
14720 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
14730 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
14740 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
14750 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
14760 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
14770 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
14780 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
14790 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
147a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
147b0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
147c0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
147d0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
147e0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
147f0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
14800 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
14810 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
14820 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
14830 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
14840 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
14850 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
14860 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
14870 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
14880 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
14890 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
148a0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
148b0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
148c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
148d0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
148e0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
148f0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
14900 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
14910 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
14920 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
14930 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
14940 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
14950 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
14960 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
14970 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
14980 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
14990 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
149a0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
149b0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
149c0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
149d0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
149e0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
149f0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
14a00 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73  ..**.** Only a s
14a10 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
14a20 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
14a30 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
14a40 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
14a50 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
14a60 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
14a70 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
14a80 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
14a90 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
14aa0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
14ab0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
14ac0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
14ad0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
14ae0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
14af0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14b00 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
14b10 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
14b20 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
14b30 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
14b40 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
14b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
14b60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
14b70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14b80 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
14b90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14ba0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
14bb0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
14bc0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
14bd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14be0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
14bf0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
14c00 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
14c10 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  aph..**.** When 
14c20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14c30 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
14c40 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
14c50 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
14c60 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
14c70 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 69   reprepared duri
14c80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
14c90 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
14ca0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
14cb0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
14cc0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
14cd0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
14ce0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
14cf0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
14d00 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
14d10 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
14d20 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
14d30 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
14d40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14d50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
14d60 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
14d70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
14d80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
14d90 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
14da0 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
14db0 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
14dc0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
14dd0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
14de0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
14df0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
14e00 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
14e10 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
14e20 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
14e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14e40 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
14e50 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
14e60 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
14e70 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nge..**.** Requi
14e80 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
14e90 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48  501] [H12502] [H
14ea0 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20  12503] [H12504] 
14eb0 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36  [H12505] [H12506
14ec0 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35  ] [H12507] [H125
14ed0 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20  10].** [H12511] 
14ee0 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30  [H12512] [H12520
14ef0 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35  ] [H12521] [H125
14f00 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  22].*/.int sqlit
14f10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14f20 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
14f30 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
14f40 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14f50 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
14f60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
14f70 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
14f80 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
14f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14fa0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
14fb0 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d  n Codes {H12590}
14fc0 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
14fd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
14fe0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
14ff0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15000 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
15010 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
15020 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
15030 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
15040 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
15050 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
15060 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
15070 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
15080 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
15090 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
150a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
150b0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
150c0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
150d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
150e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
150f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15100 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
15110 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
15120 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
15130 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
15140 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
15150 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
15160 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
15170 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
15180 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
15190 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
151a0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
151b0 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35  s {H12550} <H125
151c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
151d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
151e0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
151f0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
15200 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
15210 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
15220 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
15230 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
15240 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
15250 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
15260 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
15270 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15280 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
15290 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
152a0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
152b0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
152c0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
152d0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
152e0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
152f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15300 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
15310 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
15320 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
15330 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
15340 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
15350 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
15360 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
15370 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
15380 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
15390 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
153a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
153b0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
153c0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
153d0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
153e0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
153f0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
15400 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
15410 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
15420 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
15430 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15440 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
15450 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
15460 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
15470 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
15480 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
15490 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
154a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
154b0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
154c0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
154d0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
154e0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
154f0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
15500 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
15510 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
15520 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
15530 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
15540 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
15550 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52  QL code..**.** R
15560 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
15570 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32  [H12551] [H12552
15580 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35  ] [H12553] [H125
15590 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  54].*/./********
155a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
155b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
155c0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
155d0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
155e0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
155f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
15600 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
15610 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
15620 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
15630 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15640 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
15650 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
15660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15670 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15690 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
156a0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
156b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
156c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
156d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
156e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
156f0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
15700 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15710 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15730 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
15740 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
15750 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
15760 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15780 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
15790 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
157a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
157b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
157c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
157d0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
157e0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
157f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15800 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15820 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
15830 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
15840 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
15850 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
15870 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
15880 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
15890 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
158a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
158b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
158c0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
158d0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
158e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
158f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15900 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
15910 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
15920 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
15930 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15940 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15950 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15960 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
15970 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
15980 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
15990 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
159a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
159b0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
159c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
159d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
159e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
159f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15a00 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
15a10 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
15a20 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
15a30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15a40 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15a50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
15a60 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
15a70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15a80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15a90 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
15aa0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
15ab0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
15ac0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15ad0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15ae0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
15af0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
15b00 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15b10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15b20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15b30 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
15b40 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
15b50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15b60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15b70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15b80 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
15b90 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
15ba0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
15bb0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
15bc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15bd0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
15be0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
15bf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
15c00 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
15c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15c20 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
15c30 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
15c40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
15c50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15c70 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
15c80 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
15c90 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
15ca0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
15cc0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
15cd0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
15ce0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
15cf0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
15d00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
15d10 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
15d20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
15d30 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
15d40 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
15d60 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
15d70 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
15d80 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
15d90 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
15db0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
15dc0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
15dd0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
15de0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15df0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
15e00 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
15e10 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
15e20 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15e30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15e40 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
15e50 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
15e60 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
15e70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15e80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15e90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
15ea0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
15eb0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15ec0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
15ed0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15ee0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
15ef0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
15f00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15f10 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
15f20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15f30 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
15f40 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
15f50 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
15f60 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
15f70 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
15f80 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
15f90 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
15fa0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
15fb0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
15fc0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
15fd0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
15fe0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
15ff0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
16000 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16010 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
16020 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
16030 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
16040 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
16050 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
16060 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
16070 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
16080 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
16090 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
160a0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
160b0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
160c0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
160d0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
160e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
160f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
16100 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
16110 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
16120 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
16130 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
16140 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
16150 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
16160 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
16170 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16180 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
16190 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
161a0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
161b0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
161c0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
161d0 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
161e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
161f0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
16200 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
16210 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
16220 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
16230 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
16240 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
16250 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
16260 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
16270 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
16280 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
16290 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
162a0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
162b0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
162c0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
162d0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
162e0 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
162f0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
16300 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
16310 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
16320 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
16330 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
16340 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
16350 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
16360 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
16370 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
16380 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48  :.** [H12281] [H
16390 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20  12282] [H12283] 
163a0 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35  [H12284] [H12285
163b0 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32  ] [H12287] [H122
163c0 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20  88] [H12289].** 
163d0 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49  [H12290].*/.SQLI
163e0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
163f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
16400 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
16410 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
16420 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
16430 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
16440 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
16450 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
16460 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
16470 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
16480 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
16490 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
164a0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
164b0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
164c0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
164d0 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36  cks {H12910} <S6
164e0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0400>.**.** This
164f0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
16500 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
16510 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
16520 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
16530 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
16540 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
16550 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
16560 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
16570 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
16580 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
16590 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
165a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
165b0 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
165c0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
165d0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
165e0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
165f0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
16600 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66   query..**.** If
16610 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
16620 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
16630 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
16640 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
16650 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
16660 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
16670 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
16680 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
16690 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
166a0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
166b0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
166c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
166d0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
166e0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
166f0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
16700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16710 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
16720 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
16730 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
16740 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16750 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
16760 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
16770 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
16780 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16790 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
167a0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
167b0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
167c0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  aph..**.** Requi
167d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
167e0 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48  911] [H12912] [H
167f0 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20  12913] [H12914] 
16800 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36  [H12915] [H12916
16810 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39  ] [H12917] [H129
16820 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  18].**.*/.void s
16830 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
16840 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
16850 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
16860 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
16870 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
16880 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
16890 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
168a0 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30   {H12700} <S4020
168b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
168c0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
168d0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
168e0 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
168f0 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
16900 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
16910 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61  ment. The filena
16920 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
16930 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
16940 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
16950 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
16960 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
16970 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
16980 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
16990 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
169a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
169b0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
169c0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
169d0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
169e0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
169f0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
16a00 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
16a10 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
16a20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
16a30 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
16a40 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
16a50 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
16a60 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
16a70 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
16a80 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
16a90 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
16aa0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
16ab0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
16ac0 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  t. If the databa
16ad0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
16ae0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
16af0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
16b00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
16b10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
16b20 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
16b30 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
16b40 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
16b50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
16b60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
16b70 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
16b80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16b90 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
16ba0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
16bb0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
16bc0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
16bd0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
16be0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
16bf0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
16c00 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
16c10 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
16c20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
16c30 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
16c40 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
16c50 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
16c60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16c70 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
16c80 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
16c90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
16ca0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
16cb0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
16cc0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
16cd0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16ce0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
16cf0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
16d00 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
16d10 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
16d20 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
16d30 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
16d40 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
16d50 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
16d60 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
16d70 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
16d80 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
16d90 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
16da0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
16db0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
16dc0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
16dd0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
16de0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
16df0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
16e00 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
16e10 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
16e20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
16e30 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
16e40 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
16e50 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
16e60 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
16e70 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
16e80 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
16e90 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ags:.**.** <dl>.
16ea0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
16eb0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
16ec0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
16ed0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16ee0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
16ef0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
16f00 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
16f10 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
16f20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
16f30 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
16f40 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
16f50 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
16f60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
16f70 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
16f80 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
16f90 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
16fa0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
16fb0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
16fc0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
16fd0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
16fe0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
16ff0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
17000 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
17010 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
17020 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
17030 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
17040 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
17050 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
17060 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
17070 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
17080 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
17090 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
170a0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
170b0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
170c0 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
170d0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
170e0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
170f0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
17100 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
17110 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
17120 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17130 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
17140 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
17150 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
17160 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
17170 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
17180 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
17190 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
171a0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
171b0 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
171c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
171d0 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
171e0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
171f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
17200 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
17210 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
17220 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  lags,.** then th
17230 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
17240 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
17250 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
17260 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
17270 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
17280 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17290 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
172a0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
172b0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
172c0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
172d0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
172e0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
172f0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
17300 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
17310 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65  rt-time.  If the
17320 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
17330 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
17340 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
17350 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17360 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
17370 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
17380 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
17390 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
173a0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
173b0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
173c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
173d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
173e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
173f0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
17400 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
17410 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
17420 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
17430 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
17440 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
17450 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
17460 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
17470 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
17480 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17490 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
174a0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
174b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
174c0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
174d0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
174e0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
174f0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
17500 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
17510 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
17520 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
17530 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
17540 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
17550 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
17560 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
17570 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
17580 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
17590 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
175a0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
175b0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
175c0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
175d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
175e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
175f0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
17600 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
17610 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
17620 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
17630 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
17640 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
17650 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
17660 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
17670 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
17680 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
17690 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
176a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
176b0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
176c0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
176d0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
176e0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
176f0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
17700 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
17710 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
17720 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
17730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17740 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
17750 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17760 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
17770 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
17780 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
17790 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
177a0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
177b0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
177c0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
177d0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
177e0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
177f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
17800 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
17810 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
17820 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
17830 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
17840 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
17850 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
17860 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
17870 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
17880 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
17890 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
178a0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
178b0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
178c0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
178d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
178e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
178f0 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  )..**.** Require
17900 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30  ments:.** [H1270
17910 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32  1] [H12702] [H12
17920 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48  703] [H12704] [H
17930 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20  12706] [H12707] 
17940 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31  [H12709] [H12711
17950 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48  ].** [H12712] [H
17960 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20  12713] [H12714] 
17970 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39  [H12717] [H12719
17980 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37  ] [H12721] [H127
17990 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  23].*/.int sqlit
179a0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
179b0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
179c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
179d0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
179e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
179f0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
17a00 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17a10 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
17a20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
17a30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
17a40 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17a50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17a60 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
17a70 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
17a80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
17a90 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
17aa0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
17ab0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
17ac0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
17ad0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17ae0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
17af0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
17b00 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
17b10 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17b20 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
17b30 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
17b40 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
17b50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
17b60 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
17b70 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
17b80 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
17b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
17ba0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
17bb0 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
17bc0 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
17bd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
17be0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
17bf0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
17c00 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
17c10 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
17c20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
17c30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17c40 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
17c50 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
17c60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
17c70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17c80 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
17c90 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
17ca0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
17cb0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
17cc0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
17cd0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
17ce0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
17cf0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
17d00 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
17d10 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
17d20 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
17d30 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
17d40 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
17d50 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
17d60 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
17d70 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
17d80 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
17d90 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
17da0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
17db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
17dc0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
17dd0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
17de0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
17df0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
17e00 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
17e10 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
17e20 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
17e30 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
17e40 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
17e50 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
17e60 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
17e70 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
17e80 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
17e90 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
17ea0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
17eb0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
17ec0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
17ed0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
17ee0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
17ef0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
17f00 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
17f10 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
17f20 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
17f30 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
17f40 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
17f50 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
17f60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
17f70 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
17f80 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
17f90 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
17fa0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
17fb0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17fc0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
17fd0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
17fe0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
17ff0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
18000 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
18010 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
18020 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
18030 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
18040 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
18050 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
18060 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
18070 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
18080 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
18090 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
180a0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
180b0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
180c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
180d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
180e0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
180f0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
18100 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
18110 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
18120 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
18130 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
18140 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
18150 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
18160 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
18170 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
18180 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
18190 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
181a0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
181b0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
181c0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
181d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
181e0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
181f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
18200 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
18210 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
18220 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
18230 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
18240 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
18250 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
18260 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
18270 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
18280 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32  ** [H12801] [H12
18290 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48  802] [H12803] [H
182a0 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20  12807] [H12808] 
182b0 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12809].*/.int 
182c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
182d0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
182e0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
182f0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
18300 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
18310 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
18320 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
18330 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
18340 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
18350 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18360 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
18370 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
18380 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
18390 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
183a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
183b0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
183c0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
183d0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
183e0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
183f0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
18400 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
18410 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
18420 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
18430 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
18440 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
18450 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
18460 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
18470 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
18480 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
18490 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
184a0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
184b0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
184c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
184d0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
184e0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
184f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18500 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
18510 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
18520 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
18530 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
18540 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
18550 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
18560 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
18570 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
18580 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
18590 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
185a0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
185b0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
185c0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
185d0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
185e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
185f0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
18600 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
18610 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
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 44 65 73 74 72 6f 79 20  ** <li> Destroy 
18640 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
18650 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
18660 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
18670 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
18680 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
18690 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
186a0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
186b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
186c0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
186d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
186e0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
186f0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
18700 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
18710 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
18720 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
18730 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
18740 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
18750 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
18760 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
18770 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
18780 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
18790 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
187a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
187b0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
187c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
187d0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
187e0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
187f0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
18800 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
18810 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
18820 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
18830 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
18840 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
18850 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
18860 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
18870 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
18880 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
18890 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
188a0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
188b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
188c0 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
188d0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
188e0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
188f0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
18900 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
18910 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
18920 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
18930 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
18940 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
18950 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
18960 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
18970 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
18980 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
18990 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
189a0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
189b0 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
189c0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
189d0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
189e0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
189f0 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
18a00 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
18a10 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
18a20 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
18a30 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
18a40 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
18a50 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
18a60 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
18a70 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
18a80 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
18a90 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
18aa0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
18ab0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
18ac0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
18ad0 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
18ae0 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
18af0 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
18b00 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
18b10 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
18b20 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
18b30 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
18b40 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
18b50 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
18b60 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
18b70 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
18b80 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
18b90 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
18ba0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
18bb0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
18bc0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
18bd0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
18be0 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
18bf0 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
18c00 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
18c10 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
18c20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
18c30 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
18c40 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
18c50 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
18c60 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
18c70 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
18c80 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
18c90 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
18ca0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
18cb0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
18cc0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18cd0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
18ce0 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
18cf0 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
18d00 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
18d10 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
18d20 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
18d30 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
18d40 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
18d50 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
18d60 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
18d70 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
18d80 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
18d90 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
18da0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
18db0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
18dc0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
18dd0 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48  :.** [H12762] [H
18de0 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a  12766] [H12769].
18df0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
18e00 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
18e10 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
18e20 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18e30 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
18e40 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
18e50 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e  H12790} <H12760>
18e60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
18e70 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
18e80 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
18e90 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
18ea0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
18eb0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
18ec0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
18ed0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
18ee0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
18ef0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
18f00 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
18f10 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
18f20 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
18f30 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
18f40 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
18f50 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
18f60 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
18f70 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
18f80 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
18f90 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
18fa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18fb0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
18fc0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18fd0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
18fe0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
18ff0 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
19000 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
19010 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
19020 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19030 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
19040 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
19050 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
19060 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
19070 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
19080 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
19090 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
190a0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
190b0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
190c0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
190d0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
190e0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
190f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
19100 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
19110 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
19120 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
19130 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
19140 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
19150 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
19160 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
19170 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
19180 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
19190 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
191a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
191b0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
191c0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
191d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
191e0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
191f0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
19200 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
19210 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19220 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
19230 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
19240 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
19250 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
19260 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
19270 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
19280 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
19290 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
192a0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
192b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
192c0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
192d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
192e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
192f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
19300 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
19310 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19320 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
19330 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19340 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
19350 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
19360 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
19370 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19380 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
19390 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
193a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
193b0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
193c0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
193d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
193e0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
193f0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
19400 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19410 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
19420 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
19430 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
19440 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
19450 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
19460 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
19470 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
19480 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
19490 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
194a0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
194b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
194c0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
194d0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
194e0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
194f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
19500 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
19510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19520 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
19530 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
19540 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
19550 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
19560 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
19570 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
19580 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
19590 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
195a0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
195b0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
195c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
195d0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
195e0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
195f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
19600 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
19610 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
19620 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
19630 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
19640 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
19650 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
19660 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
19670 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
19680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
19690 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
196a0 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
196b0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
196c0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
196d0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
196e0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
196f0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
19700 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
19710 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
19720 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
19730 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
19740 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
19750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19760 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
19770 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
19780 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
19790 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
197a0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
197b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
197c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
197d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
197e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
197f0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
19800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19810 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
19820 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
19830 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
19840 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
19850 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
19860 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
19870 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
19880 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
19890 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
198a0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
198b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
198c0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
198d0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
198e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
198f0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
19900 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
19910 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
19920 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
19930 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
19940 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
19950 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
19960 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
19970 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
19980 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20  nator. If nByte 
19990 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
199a0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
199b0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
199c0 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
199d0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
199e0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
199f0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
19a00 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
19a10 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
19a20 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
19a30 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
19a40 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
19a50 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
19a60 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
19a70 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
19a80 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
19a90 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
19aa0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
19ab0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
19ac0 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
19ad0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
19ae0 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
19af0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
19b00 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
19b10 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
19b20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
19b30 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
19b40 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
19b50 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
19b60 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
19b70 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  r bytes..**.** I
19b80 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
19b90 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
19ba0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
19bb0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
19bc0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
19bd0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
19be0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
19bf0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
19c00 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
19c10 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
19c20 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
19c30 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
19c40 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
19c50 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
19c60 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
19c70 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
19c80 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
19c90 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
19ca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19cb0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
19cc0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
19cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19ce0 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
19cf0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
19d00 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
19d10 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
19d20 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19d30 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
19d40 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
19d50 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
19d60 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
19d70 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
19d80 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
19d90 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
19da0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
19db0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
19dc0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
19dd0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
19de0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
19df0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
19e00 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
19e10 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
19e20 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
19e30 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
19e40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
19e50 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
19e60 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
19e70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
19e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19e90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
19ea0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19eb0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
19ec0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
19ed0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
19ee0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
19ef0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
19f00 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
19f10 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
19f20 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19f30 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
19f40 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
19f50 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
19f60 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
19f70 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19f80 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
19f90 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
19fa0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
19fb0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
19fc0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
19fd0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
19fe0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
19ff0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1a000 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1a010 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
1a020 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
1a030 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1a040 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
1a050 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1a060 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1a070 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1a080 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1a090 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1a0a0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1a0b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1a0c0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1a0d0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1a0e0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1a0f0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1a100 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
1a110 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
1a120 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
1a130 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
1a140 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
1a150 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
1a160 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
1a170 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
1a180 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
1a190 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
1a1a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
1a1b0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1a1c0 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74   is.** now a fat
1a1d0 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
1a1e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1a1f0 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
1a200 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
1a210 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
1a220 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
1a230 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1a240 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
1a250 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
1a260 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
1a270 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
1a280 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
1a290 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  turn..** </li>.*
1a2a0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
1a2b0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
1a2c0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
1a2d0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
1a2e0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
1a2f0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
1a300 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
1a310 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
1a320 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   The legacy beha
1a330 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1a340 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a350 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1a360 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1a370 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1a380 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1a390 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
1a3a0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1a3b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a3c0 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64  _reset()] in ord
1a3d0 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  er.** to find th
1a3e0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1a3f0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1a400 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1a410 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1a420 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1a430 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1a440 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1a450 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1a460 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1a470 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71   </ol>.**.** Req
1a480 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1a490 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20  13011] [H13012] 
1a4a0 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34  [H13013] [H13014
1a4b0 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30  ] [H13015] [H130
1a4c0 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31  16] [H13019] [H1
1a4d0 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20  3021].**.*/.int 
1a4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a4f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a500 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a510 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a520 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1a530 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a540 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a550 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1a560 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1a570 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1a580 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1a590 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1a5a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1a5b0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1a5c0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1a5d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a5e0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1a5f0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1a600 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1a610 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1a620 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1a630 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1a640 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a650 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a660 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a670 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1a680 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a690 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1a6a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a6c0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a6d0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a6e0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a6f0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1a700 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1a710 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a720 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1a730 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1a740 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1a750 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1a760 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1a770 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1a780 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a790 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a7a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a7b0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1a7c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a7d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1a7e0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a7f0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a800 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a810 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a820 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a830 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a840 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a850 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a860 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1a870 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a880 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a890 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a8a0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1a8b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a8c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1a8d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1a8e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1a8f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1a900 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1a910 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1a920 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1a930 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a940 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a950 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a960 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a970 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a980 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a990 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a9a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a9b0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1a9c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a9d0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a9e0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a9f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1aa00 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1aa10 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48  Statement SQL {H
1aa20 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a  13100} <H13000>.
1aa30 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1aa40 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1aa50 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1aa60 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1aa70 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1aa80 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1aa90 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1aaa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1aab0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1aac0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1aad0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1aae0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1aaf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1ab00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1ab10 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1ab20 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b  s:.** [H13101] [
1ab30 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d  H13102] [H13103]
1ab40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ab50 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1ab60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1ab70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ab80 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1ab90 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1aba0 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
1abb0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1abc0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1abd0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1abe0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1abf0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1ac00 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1ac10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ac20 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1ac30 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1ac40 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1ac50 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1ac60 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1ac70 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1ac80 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1ac90 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
1aca0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1acb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1acc0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1acd0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1ace0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1acf0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1ad00 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1ad10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ad20 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1ad30 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1ad40 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1ad50 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1ad60 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1ad70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ad80 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1ad90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1ada0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1adb0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1adc0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1add0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1ade0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1adf0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1ae00 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1ae10 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1ae20 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1ae30 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1ae40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ae50 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1ae60 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1ae70 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1ae80 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1ae90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1aea0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1aeb0 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1aec0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1aed0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1aee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1aef0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1af00 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1af10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1af20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1af30 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1af40 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1af50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1af60 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1af70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1af80 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1af90 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1afa0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1afb0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1afc0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1afd0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1afe0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1aff0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1b000 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1b010 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1b020 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1b030 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1b040 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1b050 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1b060 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1b070 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1b080 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1b090 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1b0a0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1b0b0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1b0c0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1b0d0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1b0e0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1b0f0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1b100 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1b110 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1b120 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1b130 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1b140 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b150 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1b160 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1b170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1b180 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1b190 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1b1a0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1b1b0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1b1c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b1d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1b1e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1b1f0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1b200 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1b210 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1b220 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1b230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1b240 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1b250 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1b260 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1b270 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1b280 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1b290 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1b2a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1b2b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1b2c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1b2d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1b2e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1b2f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1b300 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1b310 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1b320 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1b330 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1b340 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1b350 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1b360 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1b370 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1b380 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1b390 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
1b3a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
1b3b0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1b3c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1b3d0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1b3e0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1b3f0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1b400 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1b410 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1b420 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1b430 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1b440 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1b450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1b460 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1b470 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1b480 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1b490 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1b4a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1b4b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1b4c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1b4d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1b4e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1b4f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1b500 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1b510 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1b520 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1b530 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1b540 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1b550 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1b560 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1b570 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1b580 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1b590 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1b5a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1b5b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1b5c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1b5d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1b5e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1b5f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1b600 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
1b610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1b620 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1b630 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1b640 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1b650 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1b660 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1b670 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1b680 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1b690 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
1b6a0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1b6b0 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1b6c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b6d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1b6e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1b6f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1b700 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1b710 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
1b720 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
1b730 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1b740 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1b750 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1b760 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1b770 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1b780 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
1b790 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
1b7a0 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
1b7b0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1b7c0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
1b7d0 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
1b7e0 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
1b7f0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
1b800 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1b810 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1b820 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1b830 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1b840 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1b850 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1b860 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1b870 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1b880 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1b890 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1b8a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1b8b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1b8c0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1b8d0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1b8e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1b8f0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1b900 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1b910 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b920 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1b930 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
1b940 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1b950 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1b960 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1b970 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
1b980 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1b990 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1b9a0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
1b9b0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
1b9c0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1b9d0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1b9e0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1b9f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1ba00 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1ba10 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1ba20 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1ba30 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
1ba40 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
1ba50 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
1ba60 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
1ba70 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
1ba80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ba90 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
1baa0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1bab0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1bac0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1bad0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1bae0 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1baf0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1bb00 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1bb10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1bb20 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
1bb30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
1bb40 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
1bb50 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1bb60 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1bb70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1bb80 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1bb90 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1bba0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1bbb0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1bbc0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1bbd0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1bbe0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1bbf0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1bc00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1bc10 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1bc20 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1bc30 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1bc40 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1bc50 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1bc60 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1bc70 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
1bc80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bc90 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1bca0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1bcb0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1bcc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1bcd0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1bce0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1bcf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1bd00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bd10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1bd20 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1bd30 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1bd40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1bd50 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1bd60 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1bd70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1bd80 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1bd90 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1bda0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1bdb0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1bdc0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1bdd0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1bde0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1bdf0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1be00 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1be10 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1be20 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1be30 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1be40 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1be50 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1be60 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1be70 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1be80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1be90 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1bea0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1beb0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1bec0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1bed0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1bee0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1bef0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1bf00 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1bf10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1bf20 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1bf30 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1bf40 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1bf50 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1bf60 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
1bf70 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1bf80 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1bf90 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1bfa0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1bfb0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1bfc0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1bfd0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1bfe0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1bff0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1c000 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1c010 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1c020 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1c030 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1c040 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1c050 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1c060 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1c070 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
1c080 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1c090 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1c0a0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1c0b0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1c0c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1c0d0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1c0e0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1c0f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1c100 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1c110 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1c120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1c130 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1c140 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1c150 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1c160 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1c170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1c180 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1c190 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1c1a0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1c1b0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1c1c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1c1d0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1c1e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1c1f0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1c200 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1c210 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1c220 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1c230 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1c240 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1c250 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1c260 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1c270 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1c280 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1c290 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1c2a0 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1c2b0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1c2c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1c2d0 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1c2e0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1c2f0 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1c300 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1c310 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1c320 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1c330 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1c340 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1c350 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1c360 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1c370 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1c380 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1c390 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1c3a0 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1c3b0 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1c3c0 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1c3d0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1c3e0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1c3f0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1c400 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1c410 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1c420 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1c430 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1c440 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1c450 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1c460 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c470 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1c480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c490 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1c4a0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1c4b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30  ments:.** [H1350
1c4c0 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33  6] [H13509] [H13
1c4d0 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48  512] [H13515] [H
1c4e0 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20  13518] [H13521] 
1c4f0 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37  [H13524] [H13527
1c500 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48  ].** [H13530] [H
1c510 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20  13533] [H13536] 
1c520 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32  [H13539] [H13542
1c530 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35  ] [H13545] [H135
1c540 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a  48] [H13551].**.
1c550 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c560 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1c570 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1c580 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1c590 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1c5a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c5b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1c5c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1c5d0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1c5e0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1c5f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c600 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1c610 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1c620 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c630 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1c640 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c650 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1c660 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1c670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c680 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1c690 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1c6a0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1c6b0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c6c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c6d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1c6e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1c6f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1c700 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1c710 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1c720 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c730 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1c740 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1c750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1c760 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1c770 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1c780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c790 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1c7a0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
1c7b0 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
1c7c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c7d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1c7e0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1c7f0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1c800 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1c810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c820 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1c830 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1c840 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1c850 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1c860 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1c870 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1c880 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1c890 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1c8a0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1c8b0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1c8c0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1c8d0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1c8e0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
1c8f0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
1c900 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
1c910 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
1c920 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
1c930 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
1c940 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1c950 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1c960 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1c970 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1c980 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
1c990 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1c9a0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1c9b0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
1c9c0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
1c9d0 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1c9e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1c9f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1ca00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1ca10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ca20 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1ca30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ca40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1ca50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1ca60 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1ca70 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a  .** [H13601].*/.
1ca80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ca90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1caa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1cab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cac0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1cad0 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
1cae0 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
1caf0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1cb00 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1cb10 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1cb20 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
1cb30 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
1cb40 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1cb50 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1cb60 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1cb70 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1cb80 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1cb90 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1cba0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1cbb0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1cbc0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1cbd0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1cbe0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1cbf0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1cc00 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1cc10 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1cc20 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1cc30 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1cc40 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1cc50 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1cc60 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1cc70 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1cc80 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1cc90 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1cca0 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
1ccb0 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
1ccc0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
1ccd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
1cce0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1ccf0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1cd00 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
1cd10 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
1cd20 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1cd30 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
1cd40 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1cd50 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1cd60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1cd70 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1cd80 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
1cd90 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1cda0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1cdb0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1cdc0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1cdd0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1cde0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1cdf0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1ce00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ce10 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ce20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1ce30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1ce40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1ce50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ce60 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1ce70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ce80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1ce90 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1cea0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1ceb0 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a  .** [H13621].*/.
1cec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ced0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1cee0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
1cef0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
1cf00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1cf10 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
1cf20 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
1cf30 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
1cf40 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
1cf50 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1cf60 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1cf70 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1cf80 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1cf90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1cfa0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1cfb0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1cfc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1cfd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1cfe0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1cff0 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1d000 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1d010 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1d020 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1d030 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1d040 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1d050 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1d060 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1d070 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1d080 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1d090 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1d0a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d0b0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1d0c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d0d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d0e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d0f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d100 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1d110 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1d120 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d130 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1d140 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1d150 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a  s:.** [H13641].*
1d160 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1d180 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
1d190 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1d1a0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
1d1b0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
1d1c0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
1d1d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1d1e0 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
1d1f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
1d200 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1d210 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1d220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1d230 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
1d240 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1d250 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1d260 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
1d270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1d280 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
1d290 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
1d2a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1d2b0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52  to NULL..**.** R
1d2c0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1d2d0 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13661].*/.int 
1d2e0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
1d2f0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
1d300 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1d310 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1d320 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
1d330 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31  esult Set {H1371
1d340 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1d350 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
1d360 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1d370 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1d380 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1d390 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1d3a0 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
1d3b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
1d3c0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1d3d0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d3e0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
1d3f0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
1d400 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
1d410 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  TE])..**.** Requ
1d420 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1d430 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3711].*/.int sql
1d440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
1d450 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1d460 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1d470 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
1d480 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
1d490 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
1d4a0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1d4b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d4c0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1d4d0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1d4e0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1d4f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1d500 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1d510 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
1d520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d530 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
1d540 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1d550 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1d560 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1d570 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
1d580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1d590 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
1d5a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1d5b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d5c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
1d5d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d5e0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
1d5f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
1d600 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
1d610 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
1d620 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
1d630 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d640 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
1d650 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1d660 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
1d670 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1d680 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1d690 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
1d6a0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
1d6b0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
1d6c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
1d6d0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
1d6e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d6f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1d700 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
1d710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d720 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1d730 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1d740 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
1d750 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
1d760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d770 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
1d780 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
1d790 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
1d7a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
1d7b0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
1d7c0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
1d7d0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
1d7e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d7f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1d800 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
1d810 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
1d820 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1d830 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
1d840 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
1d850 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
1d860 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
1d870 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
1d880 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
1d890 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
1d8a0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
1d8b0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
1d8c0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
1d8d0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
1d8e0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
1d8f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1d900 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48  :.** [H13721] [H
1d910 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20  13723] [H13724] 
1d920 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36  [H13725] [H13726
1d930 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f  ] [H13727].*/.co
1d940 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d950 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1d960 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d970 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1d980 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1d990 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1d9a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1d9b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d9c0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1d9d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1d9e0 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30  {H13740} <S10700
1d9f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1da00 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1da10 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1da20 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
1da30 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
1da40 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
1da50 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
1da60 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1da70 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
1da80 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
1da90 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
1daa0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
1dab0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
1dac0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
1dad0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
1dae0 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
1daf0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
1db00 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
1db10 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
1db20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
1db30 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
1db40 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
1db50 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
1db60 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
1db70 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
1db80 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1db90 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
1dba0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
1dbb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1dbc0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
1dbd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1dbe0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
1dbf0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
1dc00 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
1dc10 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
1dc20 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
1dc30 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
1dc40 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
1dc50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
1dc60 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
1dc70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1dc80 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
1dc90 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
1dca0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1dcb0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
1dcc0 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
1dcd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1dce0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1dcf0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
1dd00 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
1dd10 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1dd20 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1dd30 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1dd40 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1dd50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1dd60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
1dd70 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1dd80 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1dd90 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1dda0 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
1ddb0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1ddc0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1ddd0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1dde0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1ddf0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
1de00 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
1de10 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
1de20 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
1de30 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
1de40 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
1de50 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
1de60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1de70 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1de80 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
1de90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1dea0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
1deb0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1dec0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1ded0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1dee0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1def0 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1df00 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1df10 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1df20 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1df30 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1df40 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1df50 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1df60 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1df70 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1df80 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1df90 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
1dfa0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1dfb0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
1dfc0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1dfd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1dfe0 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  A13751}.** If tw
1dff0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1e000 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1e010 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1e020 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1e030 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1e040 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1e050 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1e060 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1e070 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1e080 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1e090 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1e0a0 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37  * [H13741] [H137
1e0b0 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31  42] [H13743] [H1
1e0c0 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b  3744] [H13745] [
1e0d0 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d  H13746] [H13748]
1e0e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
1e0f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1e100 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
1e110 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1e120 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
1e130 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
1e140 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
1e150 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
1e160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e170 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
1e180 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
1e190 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1e1a0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1e1b0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
1e1c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1e1d0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1e1e0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1e1f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e200 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e210 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1e220 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1e230 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
1e240 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1e250 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
1e260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e270 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1e290 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
1e2a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1e2b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1e2c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
1e2d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1e2e0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e2f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e300 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
1e310 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1e320 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1e330 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
1e340 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
1e350 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1e360 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
1e370 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1e380 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
1e390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e3a0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
1e3b0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
1e3c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
1e3d0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
1e3e0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
1e3f0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
1e400 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
1e410 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
1e420 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
1e430 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1e440 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
1e450 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
1e460 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
1e470 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
1e480 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
1e490 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1e4a0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
1e4b0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1e4c0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
1e4d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1e4e0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
1e4f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1e500 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
1e510 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
1e520 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1e530 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
1e540 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1e550 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1e560 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1e570 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
1e580 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1e590 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
1e5a0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
1e5b0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
1e5c0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
1e5d0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
1e5e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
1e5f0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
1e600 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
1e610 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
1e620 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
1e630 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
1e640 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
1e650 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e660 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e670 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e680 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e690 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e6a0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e6b0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e6c0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e6d0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e6e0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e6f0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e700 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e710 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e720 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e730 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e740 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e750 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e760 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1e770 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1e780 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1e790 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1e7a0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1e7b0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1e7c0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1e7d0 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48  :.** [H13761] [H
1e7e0 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a  13762] [H13763].
1e7f0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1e810 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
1e820 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e830 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1e840 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1e850 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e860 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1e870 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
1e880 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1e890 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30  {H13200} <S10000
1e8a0 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  >.**.** After a 
1e8b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e8c0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
1e8d0 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
1e8e0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
1e8f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e910 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
1e920 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
1e930 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
1e940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e950 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1e960 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
1e970 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
1e980 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
1e990 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1e9a0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
1e9b0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
1e9c0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
1e9d0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
1e9e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e9f0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
1ea00 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
1ea10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
1ea20 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1ea30 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
1ea40 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
1ea50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ea60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ea70 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1ea80 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
1ea90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1eaa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eab0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1eac0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
1ead0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
1eae0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
1eaf0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1eb00 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
1eb10 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
1eb20 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1eb30 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
1eb40 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
1eb50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
1eb60 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1eb70 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
1eb80 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
1eb90 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
1eba0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
1ebb0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
1ebc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
1ebd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
1ebe0 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
1ebf0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1ec00 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
1ec10 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
1ec20 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
1ec30 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1ec40 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1ec50 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
1ec60 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1ec70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1ec80 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1ec90 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1eca0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1ecb0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1ecc0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1ecd0 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1ece0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
1ecf0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
1ed00 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
1ed10 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1ed20 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
1ed30 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
1ed40 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
1ed50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
1ed60 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
1ed70 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1ed80 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
1ed90 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
1eda0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
1edb0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
1edc0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
1edd0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53  inuing..**.** [S
1ede0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
1edf0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
1ee00 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
1ee10 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
1ee20 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
1ee30 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1ee40 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1ee50 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
1ee60 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
1ee70 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
1ee80 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1ee90 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
1eea0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
1eeb0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
1eec0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
1eed0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tate..**.** If t
1eee0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1eef0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
1ef00 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
1ef10 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
1ef20 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
1ef30 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
1ef40 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
1ef50 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
1ef60 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
1ef70 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
1ef80 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
1ef90 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
1efa0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1efb0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
1efc0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
1efd0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
1efe0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
1eff0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
1f000 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1f010 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
1f020 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
1f030 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
1f040 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
1f050 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
1f060 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1f070 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1f080 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
1f090 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
1f0a0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
1f0b0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
1f0c0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
1f0d0 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
1f0e0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1f0f0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
1f100 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
1f110 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
1f120 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1f130 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
1f140 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
1f150 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
1f160 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
1f170 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
1f180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1f190 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
1f1a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f1b0 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
1f1c0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
1f1d0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1f1e0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
1f1f0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
1f200 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
1f210 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
1f220 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
1f230 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
1f240 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
1f250 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
1f260 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
1f270 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
1f280 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f290 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
1f2a0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
1f2b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1f2c0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
1f2d0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
1f2e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
1f2f0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
1f300 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
1f310 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
1f320 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
1f330 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
1f340 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1f350 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
1f360 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
1f370 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
1f380 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
1f390 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
1f3a0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
1f3b0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
1f3c0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
1f3d0 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
1f3e0 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
1f3f0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
1f400 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
1f410 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
1f420 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
1f430 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
1f440 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f450 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
1f460 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
1f470 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
1f480 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f490 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1f4a0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
1f4b0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
1f4c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1f4d0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
1f4e0 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
1f4f0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
1f500 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
1f510 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
1f520 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
1f530 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
1f540 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
1f550 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
1f560 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
1f570 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
1f580 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
1f590 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f5a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f5b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1f5c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
1f5d0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
1f5e0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
1f5f0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
1f600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f610 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
1f620 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
1f630 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1f640 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1f650 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1f660 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1f670 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1f680 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f690 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f6a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
1f6b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32  ements:.** [H132
1f6c0 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31  02] [H15304] [H1
1f6d0 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b  5306] [H15308] [
1f6e0 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H15310].*/.int s
1f6f0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
1f700 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1f720 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1f730 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
1f740 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
1f750 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
1f760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
1f770 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
1f780 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
1f790 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
1f7a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1f7b0 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37   [H13771] [H1377
1f7c0 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
1f7d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
1f7e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1f7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f800 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
1f810 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
1f820 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
1f830 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
1f840 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
1f850 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
1f860 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
1f870 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
1f880 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
1f890 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
1f8a0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
1f8b0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f8c0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
1f8d0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
1f8e0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
1f8f0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
1f900 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
1f910 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
1f920 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
1f930 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
1f940 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
1f950 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
1f960 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
1f970 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
1f980 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
1f990 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
1f9a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
1f9b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
1f9c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
1f9d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
1f9e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
1f9f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
1fa00 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
1fa10 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
1fa20 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
1fa30 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
1fa40 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
1fa50 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
1fa60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1fa70 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
1fa80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
1fa90 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
1faa0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
1fab0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
1fac0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
1fad0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
1fae0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
1faf0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
1fb00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
1fb10 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
1fb20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1fb30 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
1fb40 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
1fb50 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
1fb60 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
1fb70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
1fb80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1fb90 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
1fba0 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
1fbb0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
1fbc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1fbd0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1fbe0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
1fbf0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
1fc00 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
1fc10 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
1fc20 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
1fc30 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
1fc40 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1fc50 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
1fc60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1fc70 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
1fc80 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
1fc90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
1fca0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
1fcb0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1fcc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fcd0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1fce0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
1fcf0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1fd00 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1fd10 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
1fd20 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
1fd30 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
1fd40 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1fd50 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
1fd60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1fd70 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
1fd80 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1fd90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
1fda0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
1fdb0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
1fdc0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
1fdd0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
1fde0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1fdf0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
1fe00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
1fe10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
1fe20 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1fe30 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
1fe40 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
1fe50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fe60 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
1fe70 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
1fe80 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
1fe90 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
1fea0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1feb0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
1fec0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
1fed0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
1fee0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1fef0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
1ff00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1ff10 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1ff20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1ff30 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
1ff40 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
1ff50 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
1ff60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
1ff70 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
1ff80 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
1ff90 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
1ffa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
1ffb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ffc0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
1ffd0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
1ffe0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
1fff0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
20000 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
20010 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
20020 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
20030 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
20040 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
20050 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
20060 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
20070 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
20080 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
20090 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
200a0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
200b0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
200c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
200d0 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
200e0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
200f0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
20100 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
20110 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
20120 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
20130 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
20140 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
20150 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
20160 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
20170 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
20180 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
20190 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
201a0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
201b0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
201c0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
201d0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
201e0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
201f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
20210 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
20220 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
20230 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
20240 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
20250 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
20260 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
20270 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
20280 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
20290 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
202a0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
202b0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
202c0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
202d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
202e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
202f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20300 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
20310 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
20320 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
20330 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
20340 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
20350 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
20360 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
20370 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
20380 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
20390 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
203a0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
203b0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
203c0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
203d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
203e0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
203f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
20400 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
20410 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
20420 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
20430 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
20440 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
20450 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
20460 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20470 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
20480 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
20490 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
204a0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
204b0 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
204c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
204d0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
204e0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
204f0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
20500 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
20510 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
20520 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
20530 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
20540 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
20550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20560 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
20570 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
20580 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
20590 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
205a0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
205b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
205c0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
205d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
205e0 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
205f0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
20600 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
20610 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
20620 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
20630 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
20640 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
20650 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
20660 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
20670 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
20680 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
20690 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
206a0 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
206b0 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
206c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
206d0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
206e0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
206f0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
20700 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
20710 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
20720 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
20730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20740 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
20750 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
20760 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20770 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
20780 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
20790 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
207a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
207b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
207c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
207d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
207e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
207f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
20800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
20810 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
20820 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
20830 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
20840 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
20850 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
20860 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
20870 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
20880 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
20890 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
208a0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
208b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
208c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
208d0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
208e0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
208f0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
20900 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
20910 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
20920 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
20930 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
20940 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
20950 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
20960 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
20970 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
20980 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
20990 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
209a0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
209b0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
209c0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
209d0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
209e0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
209f0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
20a00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
20a10 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
20a20 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
20a30 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
20a40 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
20a50 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
20a60 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
20a70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
20a80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20a90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
20aa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
20ab0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
20ac0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
20ad0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
20ae0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20af0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
20b00 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20b10 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20b20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20b30 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20b40 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20b50 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20b60 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20b70 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
20b80 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
20b90 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
20ba0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
20bb0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
20bc0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
20bd0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
20be0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
20bf0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
20c00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
20c10 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
20c20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
20c30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
20c40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
20c50 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
20c60 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
20c70 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20c80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20c90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
20ca0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
20cb0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
20cc0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
20cd0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
20ce0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
20cf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
20d00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
20d10 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
20d20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20d30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
20d40 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
20d50 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
20d60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
20d70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20d80 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
20d90 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
20da0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
20db0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
20dc0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
20dd0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20de0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
20df0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
20e00 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
20e10 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
20e20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
20e30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20e40 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
20e50 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
20e60 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
20e70 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
20e80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
20e90 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
20ea0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
20eb0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
20ec0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
20ed0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
20ee0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
20ef0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
20f00 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
20f10 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
20f20 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
20f30 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
20f40 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
20f50 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
20f60 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
20f70 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
20f80 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
20f90 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
20fa0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
20fb0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
20fc0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
20fd0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
20fe0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
20ff0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
21000 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
21010 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
21020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21030 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
21040 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
21050 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
21060 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
21070 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
21080 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
21090 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
210a0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
210b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
210c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
210d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
210e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
210f0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
21100 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
21110 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
21120 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
21130 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
21140 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
21150 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
21160 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
21170 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
21180 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
21190 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
211a0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
211b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
211c0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
211d0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
211e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
211f0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
21200 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
21210 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
21220 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
21230 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
21240 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
21250 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
21260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21270 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
21280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21290 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
212a0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
212b0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
212c0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
212d0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
212e0 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
212f0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
21300 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
21310 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
21320 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
21330 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
21340 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
21350 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
21360 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
21370 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
21380 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
21390 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
213a0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
213b0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
213c0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
213d0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
213e0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
213f0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
21400 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
21410 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
21420 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
21430 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
21440 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
21450 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
21460 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
21470 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
21480 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
21490 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
214a0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
214b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
214c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
214d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
214e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
214f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
21500 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21510 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
21520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
21530 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
21540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21550 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
21560 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
21570 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
21580 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
21590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
215a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
215b0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
215c0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
215d0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
215e0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
215f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21600 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
21610 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
21620 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
21630 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
21640 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
21650 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
21660 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
21670 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
21680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21690 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
216a0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
216b0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
216c0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
216d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
216e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
216f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21700 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
21710 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
21720 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
21730 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
21740 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
21750 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
21760 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
21770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21780 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
21790 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
217a0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
217b0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
217c0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
217d0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
217e0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
217f0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
21800 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21810 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21820 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
21830 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
21840 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
21850 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
21860 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
21870 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
21880 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
21890 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
218a0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
218b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
218c0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
218d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
218e0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
218f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
21900 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
21910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
21920 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
21930 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
21940 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21950 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
21960 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
21970 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
21980 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
21990 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
219a0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
219b0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
219c0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
219d0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
219e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
219f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
21a00 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
21a10 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
21a20 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
21a30 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
21a40 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b  3803] [H13806] [
21a50 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d  H13809] [H13812]
21a60 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31   [H13815] [H1381
21a70 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33  8] [H13821] [H13
21a80 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d  824].** [H13827]
21a90 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e   [H13830].*/.con
21aa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21ab0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
21ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21ad0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21af0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21b00 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
21b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21b20 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
21b30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
21b40 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
21b50 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
21b60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21b70 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
21b80 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
21b90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21ba0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
21bb0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
21bc0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
21bd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21be0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
21bf0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
21c00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
21c10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21c20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
21c30 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21c40 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
21c50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21c60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
21c70 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
21c80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21c90 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
21ca0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
21cb0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
21cc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21cd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21ce0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
21cf0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
21d00 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
21d10 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
21d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
21d30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
21d40 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
21d50 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
21d60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21d70 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
21d80 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
21d90 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
21da0 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
21db0 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
21dc0 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
21dd0 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
21de0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
21df0 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
21e00 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
21e10 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
21e20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
21e30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
21e40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
21e50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
21e60 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
21e70 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
21e80 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
21e90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21ea0 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
21eb0 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
21ec0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
21ed0 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
21ee0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
21ef0 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
21f00 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
21f10 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
21f20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
21f30 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
21f40 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
21f50 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
21f60 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
21f70 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
21f80 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
21f90 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
21fa0 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
21fb0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
21fc0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
21fd0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
21fe0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
21ff0 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20  ts:.** [H11302] 
22000 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20  [H11304].*/.int 
22010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22030 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22040 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
22050 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
22060 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33  nt Object {H1333
22070 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
22080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
22090 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
220a0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
220b0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
220c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
220d0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
220e0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
220f0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
22100 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
22110 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
22120 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
22130 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
22140 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
22150 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22160 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
22170 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
22180 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
22190 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
221a0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
221b0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
221c0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
221d0 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {H11332} The [sq
221e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
221f0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
22200 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22210 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
22220 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
22230 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
22240 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
22250 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20  .** {H11334} If 
22260 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22270 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22280 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
22290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
222a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
222b0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
222c0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
222d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
222e0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
222f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
22300 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
22310 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
22320 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
22330 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
22340 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
22350 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
22360 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74  ** {H11336} If t
22370 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
22380 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22390 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
223a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
223b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
223c0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
223d0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
223e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
223f0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
22400 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
22410 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
22420 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20  .**.** {H11338} 
22430 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
22440 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
22450 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
22460 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
22470 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
22480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22490 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
224a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
224b0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
224c0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
224d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
224e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
224f0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
22500 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
22510 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d  nctions {H16100}
22520 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
22530 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
22540 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
22550 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
22560 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
22570 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
22580 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
22590 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
225a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
225b0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
225c0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
225d0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
225e0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
225f0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
22600 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
22610 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
22620 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
22630 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
22640 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
22650 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
22660 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
22670 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
22680 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
22690 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
226a0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
226b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
226c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
226d0 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
226e0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
226f0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
22700 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
22710 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
22720 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
22730 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
22740 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
22750 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
22760 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
22770 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
22780 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
22790 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
227a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
227b0 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73  e added.  If a s
227c0 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73  ingle program us
227d0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
227e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
227f0 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c  nection internal
22800 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e  ly, then SQL fun
22810 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
22820 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
22830 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74  y to.** each dat
22840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
22860 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22870 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
22890 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
228a0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65   redefined.  The
228b0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
228c0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
228d0 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
228e0 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65  lusive of.** the
228f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
22900 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
22910 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
22920 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
22930 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
22940 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
22950 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
22960 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
22970 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
22980 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
22990 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
229a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
229b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
229c0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
229d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
229e0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
229f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
22a00 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
22a10 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
22a20 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
22a30 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
22a40 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
22a50 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
22a60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
22a70 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
22a80 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
22a90 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
22aa0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
22ab0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
22ac0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
22ad0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
22ae0 6d 75 73 74 20 6e 6f 74 20 62 65 20 6c 65 73 73  must not be less
22af0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
22b00 74 65 72 20 74 68 61 6e 20 32 35 35 2e 0a 2a 2a  ter than 255..**
22b10 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
22b20 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
22b30 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
22b40 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
22b50 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
22b60 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
22b70 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
22b80 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
22b90 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
22ba0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
22bb0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
22bc0 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
22bd0 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
22be0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
22bf0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
22c00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
22c10 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
22c20 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
22c30 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
22c40 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
22c50 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
22c60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
22c70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
22c80 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
22c90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
22ca0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
22cb0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
22cc0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
22cd0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
22ce0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
22cf0 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
22d00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
22d10 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
22d20 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
22d30 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
22d40 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
22d50 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
22d60 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
22d70 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
22d80 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
22d90 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
22da0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22db0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
22dc0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
22dd0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
22de0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
22df0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
22e00 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
22e10 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  Y]..**.** The fi
22e20 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
22e30 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
22e40 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
22e50 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
22e60 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
22e70 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
22e80 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
22e90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
22ea0 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
22eb0 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
22ec0 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
22ed0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
22ee0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
22ef0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
22f00 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
22f10 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
22f20 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
22f30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
22f40 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  * aggregate. A s
22f50 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
22f60 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
22f70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
22f80 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
22f90 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
22fa0 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
22fb0 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
22fc0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
22fd0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
22fe0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
22ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
23000 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
23010 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
23020 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
23030 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
23040 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
23050 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
23060 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
23070 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
23080 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
23090 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
230a0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
230b0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ks..**.** It is 
230c0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
230d0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
230e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
230f0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
23100 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
23110 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
23120 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
23130 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
23140 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
23150 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
23160 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
23170 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  gs.  SQLite will
23180 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
23190 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20  ementation most 
231a0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
231b0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
231c0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
231d0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41  tion is used.  A
231e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
231f0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
23200 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
23210 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
23220 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
23230 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
23240 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23250 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
23260 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63  ve nArg.  A func
23270 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
23280 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
23290 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
232a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
232b0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
232c0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
232d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
232e0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
232f0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
23300 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  ** A function wh
23310 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
23320 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
23330 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
23340 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
23350 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
23360 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
23370 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
23380 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
23390 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
233a0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
233b0 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * Built-in funct
233c0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
233d0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
233e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
233f0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20  d functions..** 
23400 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63  The first applic
23410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
23420 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69  nction with a gi
23430 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64  ven name overrid
23440 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d  es all.** built-
23450 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  in functions in 
23460 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
23470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
23480 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
23490 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  e..** Subsequent
234a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
234b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f  ined functions o
234c0 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  f the same name 
234d0 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a  only override .*
234e0 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74  * prior applicat
234f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23500 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61  tions that are a
23510 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f  n exact match fo
23520 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  r the.** number 
23530 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  of parameters an
23540 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f  d preferred enco
23550 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ding..**.** An a
23560 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23570 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
23580 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
23590 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
235a0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
235b0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
235c0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
235d0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
235e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
235f0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
23600 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
23610 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
23620 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
23630 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
23640 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
23650 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48  :.** [H16103] [H
23660 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20  16106] [H16109] 
23670 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38  [H16112] [H16118
23680 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31  ] [H16121] [H161
23690 32 34 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20  24] [H16127].** 
236a0 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33  [H16130] [H16133
236b0 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31  ] [H16136] [H161
236c0 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a  39] [H16142].*/.
236d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
236e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
236f0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
23700 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
23710 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
23720 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
23730 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
23740 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
23750 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
23760 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
23770 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
23780 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
23790 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
237a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
237b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
237c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
237d0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
237e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
237f0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
23800 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
23810 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
23820 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
23830 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
23840 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
23850 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
23860 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
23870 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
23880 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
23890 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
238a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
238b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
238c0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
238d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
238e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
238f0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20   Text Encodings 
23900 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30  {H10267} <S50200
23910 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a  > <H16100>.**.**
23920 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
23930 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
23940 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
23950 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
23960 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
23970 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
23980 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
23990 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
239a0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
239b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
239c0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
239d0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
239e0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
239f0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
23a00 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
23a10 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
23a20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
23a30 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
23a40 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
23a50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23a60 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
23a70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23a80 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
23a90 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
23aa0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
23ab0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
23ac0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
23ad0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
23ae0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
23af0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
23b00 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
23b10 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
23b20 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
23b30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
23b40 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
23b50 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
23b60 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
23b70 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
23b80 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
23b90 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
23ba0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
23bb0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
23bc0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
23bd0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
23be0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
23bf0 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
23c00 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
23c10 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
23c20 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
23c30 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
23c40 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
23c50 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
23c60 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23c70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
23c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23c90 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
23ca0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
23cb0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
23cc0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
23cd0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
23ce0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
23cf0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
23d00 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
23d10 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
23d20 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
23d30 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
23d40 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
23d50 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
23d60 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
23d70 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
23d80 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23d90 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
23da0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
23db0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
23dc0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
23dd0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
23de0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
23df0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
23e00 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
23e10 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
23e20 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32  ues {H15100} <S2
23e30 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
23e40 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
23e50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
23e60 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
23e70 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
23e80 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
23e90 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
23ea0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
23eb0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
23ec0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
23ed0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
23ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
23ef0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
23f00 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
23f10 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
23f20 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
23f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
23f40 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
23f50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
23f60 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
23f70 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
23f80 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
23f90 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
23fa0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
23fb0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
23fc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23fd0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
23fe0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
23ff0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
24000 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24010 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
24020 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
24030 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
24040 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
24050 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
24070 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
24080 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
24090 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
240a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
240b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
240c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
240d0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
240e0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
240f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
24100 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
24110 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
24120 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
24130 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
24140 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
24150 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
24160 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
24170 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  vior..**.** Thes
24180 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
24190 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
241a0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
241b0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
241c0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
241d0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
241e0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
241f0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
24200 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
24210 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
24220 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
24230 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
24240 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
24250 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
24260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24270 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24280 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
24290 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
242a0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
242b0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
242c0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
242d0 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
242e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
242f0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
24300 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24310 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
24320 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
24330 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
24340 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
24350 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
24360 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
24370 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
24380 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
24390 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
243a0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
243b0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
243c0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
243d0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
243e0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
243f0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
24400 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
24410 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
24420 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
24430 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
24440 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
24450 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
24460 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
24470 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
24480 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
24490 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
244a0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
244b0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
244c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
244d0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
244e0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
244f0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
24500 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
24510 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
24520 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
24530 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
24540 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
24550 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
24560 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
24570 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
24580 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
24590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
245a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
245b0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
245c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
245d0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
245e0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
245f0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
24600 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
24610 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
24620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
24630 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
24640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24650 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
24660 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24670 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
24680 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
24690 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
246a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
246b0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
246c0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
246d0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
246e0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
246f0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ers..**.** Requi
24700 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35  rements:.** [H15
24710 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48  103] [H15106] [H
24720 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20  15109] [H15112] 
24730 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38  [H15115] [H15118
24740 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31  ] [H15121] [H151
24750 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20  24].** [H15127] 
24760 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33  [H15130] [H15133
24770 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f  ] [H15136].*/.co
24780 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24790 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
247a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
247b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
247c0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
247d0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
247e0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
247f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24800 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
24810 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(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 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
24850 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
24860 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
24870 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
24880 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
24890 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
248a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
248b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
248c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
248d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
248e0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
248f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
24900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24910 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
24920 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
24930 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
24940 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
24950 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
24960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
24970 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
24980 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24990 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
249a0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
249b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
249c0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
249d0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
249e0 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20  ontext {H16210} 
249f0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
24a00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
24a10 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  n of aggregate S
24a20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
24a30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
24a40 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73   allocate.** a s
24a50 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f  tructure for sto
24a60 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
24a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24a80 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
24a90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
24aa0 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
24ab0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a  s called for a.*
24ac0 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  * particular agg
24ad0 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61  regate, SQLite a
24ae0 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20  llocates nBytes 
24af0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
24b00 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65  s out that.** me
24b10 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
24b20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
24b30 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  t. On second and
24b40 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
24b50 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
24b60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
24b70 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
24b80 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
24b90 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68  ion index,.** th
24ba0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
24bb0 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69   returned. The i
24bc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
24bd0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63   the aggregate c
24be0 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65  an use.** the re
24bf0 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
24c00 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
24c10 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61  ..**.** SQLite a
24c20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
24c30 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  es the allocated
24c40 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65   buffer when the
24c50 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75   aggregate.** qu
24c60 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
24c70 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
24c80 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
24c90 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
24ca0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
24cb0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
24cc0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
24cd0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
24ce0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
24cf0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
24d00 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
24d10 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
24d20 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
24d30 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
24d40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
24d50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
24d60 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
24d70 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
24d80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
24d90 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
24da0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
24db0 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b  6211] [H16213] [
24dc0 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d  H16215] [H16217]
24dd0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
24de0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
24df0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
24e00 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
24e10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24e20 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
24e30 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
24e40 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  240} <S20200>.**
24e50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24e60 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
24e70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
24e80 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
24e90 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
24ea0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
24eb0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
24ec0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
24ed0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
24ee0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
24ef0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
24f00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24f10 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
24f20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
24f30 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
24f40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
24f50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
24f60 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
24f70 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
24f80 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
24f90 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
24fa0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
24fb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24fc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
24fd0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
24fe0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
24ff0 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6243].*/.void *s
25000 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
25010 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25030 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
25040 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
25050 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20  ctions {H16250} 
25060 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e  <S60600><S20200>
25070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25080 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
25090 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
250a0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
250b0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
250c0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
250d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
250e0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
250f0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
25100 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25110 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
25120 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25130 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
25140 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
25150 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
25160 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
25170 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
25180 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ction..**.** Req
25190 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
251a0 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65  16253].*/.sqlite
251b0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
251c0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
251d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
251e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
251f0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
25200 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30  ary Data {H16270
25210 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
25220 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
25230 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
25240 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
25250 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
25260 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
25270 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
25280 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
25290 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
252a0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
252b0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
252c0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
252d0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
252e0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
252f0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
25300 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
25310 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
25320 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
25330 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
25340 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
25350 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
25360 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
25370 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
25380 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
25390 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
253a0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
253b0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
253c0 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
253d0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
253e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
253f0 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
25400 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
25410 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
25420 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
25430 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
25440 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
25450 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
25460 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
25470 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25480 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
25490 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
254a0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
254b0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
254c0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
254d0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
254e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
254f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
25500 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
25510 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
25520 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
25530 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
25540 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
25550 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
25560 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
25570 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
25580 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
25590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
255a0 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d  unction. If no m
255b0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
255c0 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
255d0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
255e0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
255f0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
25600 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
25610 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
25620 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
25630 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
25640 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
25650 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
25660 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
25670 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
25680 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
25690 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
256a0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
256b0 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
256c0 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
256d0 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
256e0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
256f0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
25700 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
25710 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25720 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25730 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
25740 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
25750 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
25760 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
25770 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
25780 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
25790 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20  estroyed..** If 
257a0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
257b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
257c0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
257d0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
257e0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
257f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25800 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
25810 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
25820 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
25830 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
25840 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
25850 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
25860 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
25870 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
25880 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
25890 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
258a0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
258b0 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
258c0 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
258d0 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
258e0 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
258f0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
25900 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
25910 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
25920 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
25930 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
25940 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
25950 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
25960 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  ..**.** In pract
25970 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
25980 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
25990 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
259a0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
259b0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
259c0 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
259d0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
259e0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
259f0 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
25a00 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
25a10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25a20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
25a30 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
25a40 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
25a50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25a60 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
25a70 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
25a80 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31  .** [H16272] [H1
25a90 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b  6274] [H16276] [
25aa0 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d  H16277] [H16278]
25ab0 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69   [H16279].*/.voi
25ac0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
25ad0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
25ae0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
25af0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
25b00 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
25b10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
25b20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
25b30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
25b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
25b50 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
25b60 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
25b70 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31  tor Behavior {H1
25b80 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a  0280} <S30100>.*
25b90 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
25ba0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
25bb0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
25bc0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
25bd0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
25be0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
25bf0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
25c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
25c10 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
25c20 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
25c30 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
25c40 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
25c50 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
25c60 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
25c70 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
25c80 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
25c90 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
25ca0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
25cb0 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
25cc0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
25cd0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
25ce0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
25cf0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
25d00 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
25d10 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
25d20 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
25d30 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
25d40 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
25d50 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
25d60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
25d70 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
25d80 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
25d90 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
25da0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
25db0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
25dc0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
25dd0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
25de0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
25df0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
25e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
25e10 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
25e20 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
25e30 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
25e40 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
25e50 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
25e60 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
25e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25e80 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
25e90 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
25ea0 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d  unction {H16400}
25eb0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
25ec0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
25ed0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
25ee0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
25ef0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
25f00 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
25f10 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
25f20 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
25f30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
25f40 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
25f50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
25f60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
25f70 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
25f80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
25f90 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
25fa0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
25fb0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
25fc0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
25fd0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
25fe0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
25ff0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
26000 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
26010 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26020 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
26030 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
26040 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
26050 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
26060 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
26070 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26080 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
26090 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
260a0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
260b0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
260c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
260d0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
260e0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
260f0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
26100 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
26110 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
26120 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
26130 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
26140 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
26150 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
26160 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
26170 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
26180 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
26190 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
261a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
261b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
261c0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
261d0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
261e0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
261f0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
26200 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
26210 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26220 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
26230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
26240 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
26250 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
26260 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
26270 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26280 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
26290 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
262a0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
262b0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
262c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
262d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
262e0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
262f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26300 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
26310 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
26320 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
26330 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
26340 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53   exception..** S
26350 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
26360 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
26370 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
26380 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
26390 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
263a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
263b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
263c0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
263d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
263e0 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72  e.  SQLite inter
263f0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
26400 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
26410 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
26420 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
26430 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a   UTF-8. SQLite.*
26440 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
26450 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
26460 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26470 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
26480 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
26490 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65  e order.  If the
264a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
264b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
264c0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
264d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
264e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
264f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
26500 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
26510 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
26520 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
26530 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
26540 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
26550 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
26560 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26570 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26580 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
26590 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
265a0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
265b0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
265c0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
265d0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
265e0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
265f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
26600 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
26610 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ge..** The sqlit
26620 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26630 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
26640 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
26650 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
26660 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
26670 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
26680 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
26690 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
266a0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
266b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
266c0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
266d0 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
266e0 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
266f0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
26700 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
26710 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
26720 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
26730 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
26740 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
26750 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
26760 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
26770 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
26780 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a  .  By default,.*
26790 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
267a0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
267b0 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20  .  A subsequent 
267c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
267d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
267e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
267f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
26800 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
26810 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
26820 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ROR..**.** The s
26830 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
26840 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
26850 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
26860 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
26870 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
26880 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
26890 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20  BLOB is to long 
268a0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
268b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
268c0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
268d0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
268e0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
268f0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
26900 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
26910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
26920 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  failed..**.** Th
26930 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26940 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
26950 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
26960 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
26970 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26980 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
26990 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
269a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
269b0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
269c0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
269d0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
269e0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
269f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26a00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
26a10 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
26a20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26a30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
26a40 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
26a50 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
26a60 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
26a70 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
26a80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26a90 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
26aa0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
26ab0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
26ac0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26ad0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26ae0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
26af0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26b00 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
26b10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26b20 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
26b30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
26b40 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
26b50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
26b60 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
26b70 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
26b80 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
26b90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26ba0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26bb0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
26bc0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
26bd0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
26be0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
26bf0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
26c00 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
26c10 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
26c20 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
26c30 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
26c40 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
26c50 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
26c60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
26c70 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
26c80 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
26c90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
26ca0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
26cb0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
26cc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
26cd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
26ce0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
26cf0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
26d00 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
26d10 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
26d20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26d30 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
26d40 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
26d50 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
26d60 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
26d70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
26d80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
26d90 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
26da0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
26db0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
26dc0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
26dd0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
26de0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
26df0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
26e00 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
26e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26e20 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
26e30 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
26e40 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
26e50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
26e60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
26e70 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
26e80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
26e90 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
26ea0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
26eb0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
26ec0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
26ed0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
26ee0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
26ef0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
26f00 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
26f10 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
26f20 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
26f30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26f50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
26f60 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
26f70 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
26f80 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
26f90 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
26fa0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
26fb0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
26fc0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
26fd0 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
26fe0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
26ff0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
27000 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61  the it or call a
27010 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
27020 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
27030 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
27040 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
27050 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
27060 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27070 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
27080 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
27090 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
270a0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
270b0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
270c0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
270d0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
270e0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
270f0 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
27100 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
27110 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
27120 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
27130 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
27140 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27150 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
27160 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
27170 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
27180 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27190 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
271a0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
271b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
271c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
271d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
271e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
271f0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
27200 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
27210 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
27220 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
27230 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
27240 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
27250 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
27260 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
27270 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
27280 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
27290 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
272a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
272b0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
272c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
272d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
272e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
272f0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
27300 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
27310 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27320 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27330 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
27340 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
27350 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
27360 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
27370 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
27380 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
27390 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
273a0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
273b0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
273c0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
273d0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
273e0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
273f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27400 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
27410 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
27420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
27430 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
27440 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
27450 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  fined..**.** Req
27460 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
27470 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20  16403] [H16406] 
27480 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32  [H16409] [H16412
27490 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34  ] [H16415] [H164
274a0 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31  18] [H16421] [H1
274b0 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37  6424].** [H16427
274c0 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34  ] [H16430] [H164
274d0 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31  33] [H16436] [H1
274e0 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b  6439] [H16442] [
274f0 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d  H16445] [H16448]
27500 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31  .** [H16451] [H1
27510 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b  6454] [H16457] [
27520 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d  H16460] [H16463]
27530 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
27540 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
27550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
27560 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
27570 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27580 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27590 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
275a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
275b0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
275c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
275d0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
275e0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
275f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
27600 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
27610 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
27620 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
27630 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
27640 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27650 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
27660 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
27670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27680 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
27690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
276a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
276b0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
276c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
276d0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
276e0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
276f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27700 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
27710 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
27720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27730 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
27740 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27750 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
27760 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
27770 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27780 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
27790 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
277a0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
277b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
277c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
277d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
277e0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
277f0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27800 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27810 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27820 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
27830 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27840 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
27850 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27860 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27870 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27880 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
27890 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
278a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
278b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
278c0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
278d0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
278e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
278f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
27900 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
27910 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
27920 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27930 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
27940 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
27950 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
27960 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
27970 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
27980 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
27990 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
279a0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
279b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
279c0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
279d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
279e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
279f0 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
27a00 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
27a10 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
27a20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
27a30 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
27a40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
27a50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
27a60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
27a70 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
27a80 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
27a90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27aa0 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
27ab0 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
27ac0 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
27ad0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
27ae0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
27af0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
27b00 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
27b10 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
27b20 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
27b30 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
27b40 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16LE], or [SQL
27b50 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
27b60 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
27b70 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
27b80 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
27b90 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
27ba0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
27bb0 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
27bc0 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
27bd0 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
27be0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
27bf0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
27c00 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69  vely. The.** thi
27c10 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68  rd argument migh
27c20 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54  t also be [SQLIT
27c30 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69  E_UTF16] to indi
27c40 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72 6f  cate that the ro
27c50 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73  utine.** expects
27c60 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20   pointers to be 
27c70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69  UTF-16 strings i
27c80 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
27c90 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a  e order, or the.
27ca0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20  ** argument can 
27cb0 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
27cc0 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65  _ALIGNED] if the
27cd0 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
27ce0 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
27cf0 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
27d00 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
27d10 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
27d20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
27d30 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  order..**.** A p
27d40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
27d50 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
27d60 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
27d70 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
27d80 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
27d90 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
27da0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
27db0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
27dc0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
27dd0 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
27de0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
27df0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
27e00 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
27e10 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
27e20 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
27e30 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
27e40 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
27e50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
27e60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
27e70 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
27e80 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
27e90 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
27ea0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
27eb0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
27ec0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
27ed0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  )..**.** The rem
27ee0 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
27ef0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
27f00 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
27f10 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
27f20 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
27f30 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
27f40 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
27f50 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
27f60 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
27f70 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
27f80 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
27f90 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
27fa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
27fb0 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
27fc0 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68  tered. {END}  Th
27fd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
27fe0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
27ff0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a  routine should.*
28000 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76  * return negativ
28010 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74  e, zero or posit
28020 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74  ive if the first
28030 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
28040 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74  than,.** equal t
28050 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
28060 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74  an the second st
28070 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
28080 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
28090 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
280a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
280b0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
280c0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
280d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
280e0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
280f0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
28100 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
28110 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
28120 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
28130 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
28140 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
28150 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
28160 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
28170 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
28180 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
28190 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
281a0 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
281b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
281c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
281d0 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
281e0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
281f0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
28200 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
28210 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  er calls to the.
28220 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  ** collation cre
28230 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
28240 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74  or when the [dat
28250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28260 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75  ] is closed.** u
28270 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
28280 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  ose()]..**.** Se
28290 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
282a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
282b0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
282c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
282d0 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ded16()]..**.** 
282e0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
282f0 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30   [H16603] [H1660
28300 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36  4] [H16606] [H16
28310 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48  609] [H16612] [H
28320 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20  16615] [H16618] 
28330 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36  [H16621].** [H16
28340 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48  624] [H16627] [H
28350 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16630].*/.int sq
28360 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28370 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
28380 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
28390 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
283a0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
283b0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
283c0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
283d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
283e0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
283f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
28400 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
28410 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
28420 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
28430 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
28440 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
28450 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
28460 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
28470 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
28480 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
28490 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
284a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
284b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
284c0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
284d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
284e0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
284f0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
28500 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
28510 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28520 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28530 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
28540 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
28550 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
28560 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
28570 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
28580 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
28590 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
285a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
285b0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
285c0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
285d0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
285e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
285f0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
28600 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
28610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28620 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
28630 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
28640 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
28650 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
28660 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
28670 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
28680 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
28690 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
286a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
286b0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
286c0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
286d0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
286e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
286f0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
28700 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
28710 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
28720 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
28730 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
28740 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
28750 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
28760 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
28770 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
28780 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
28790 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
287a0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
287b0 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
287c0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
287d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
287e0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
287f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
28800 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
28810 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
28820 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28830 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28840 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
28850 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28860 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
28870 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
28880 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
28890 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
288a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
288b0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
288c0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
288d0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
288e0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
288f0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
28900 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
28910 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
28920 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
28930 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
28940 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
28950 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28960 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28970 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
28980 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
28990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
289a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
289b0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
289c0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
289d0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
289e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
289f0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
28a00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28a10 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
28a20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28a30 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
28a40 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
28a50 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d  nts:.** [H16702]
28a60 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30   [H16704] [H1670
28a70 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  6].*/.int sqlite
28a80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28a90 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
28aa0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
28ab0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
28ac0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
28ad0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
28ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28af0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
28b00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
28b10 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
28b20 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
28b30 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
28b40 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
28b50 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
28b60 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
28b70 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
28b80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
28b90 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
28ba0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
28bb0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
28bc0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
28bd0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
28be0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
28bf0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
28c00 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
28c10 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
28c20 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
28c30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28c40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
28c50 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
28c60 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
28c70 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
28c80 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
28c90 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
28ca0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
28cb0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
28cc0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
28cd0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
28ce0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
28cf0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
28d00 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
28d10 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
28d20 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
28d30 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
28d40 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
28d50 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
28d60 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
28d70 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
28d80 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
28d90 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
28da0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28db0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
28dc0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
28dd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28de0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
28df0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
28e00 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
28e10 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
28e20 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
28e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
28e40 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
28e50 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
28e60 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30  {H10530} <S40410
28e70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
28e80 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
28e90 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
28ea0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
28eb0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
28ec0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
28ed0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
28ee0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
28ef0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
28f00 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
28f10 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
28f20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
28f30 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
28f40 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
28f50 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
28f60 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
28f70 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
28f80 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
28f90 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
28fa0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
28fb0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
28fc0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
28fd0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
28fe0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
28ff0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
29000 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
29010 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
29020 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
29030 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
29040 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
29050 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
29060 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
29070 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ject..**.** Requ
29080 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33  irements: [H1053
29090 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69  3] [H10536].*/.i
290a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
290b0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
290c0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
290d0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
290e0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
290f0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
29100 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
29110 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
29120 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
29130 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
29140 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
29150 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
29160 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
29170 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
29180 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
29190 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
291a0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
291b0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
291c0 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
291d0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
291e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
291f0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
29200 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
29210 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
29220 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
29230 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
29240 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
29250 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
29260 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
29270 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
29280 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
29290 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
292a0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
292b0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
292c0 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
292d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
292e0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
292f0 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
29300 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
29310 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
29320 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
29330 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
29340 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
29350 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
29360 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
29370 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
29380 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
29390 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
293a0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
293b0 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
293c0 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
293d0 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
293e0 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fter..**.** The 
293f0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
29400 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
29410 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
29420 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
29430 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
29440 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
29450 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
29460 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 68  _malloc].  Furth
29470 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
29480 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
29490 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
294a0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
294b0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
294c0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
294d0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
294e0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
294f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
29500 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
29510 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
29520 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
29530 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
29540 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
29550 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
29560 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
29570 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
29580 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
29590 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
295a0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
295b0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
295c0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
295d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
295e0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
295f0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
29600 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
29610 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
29620 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
29630 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
29640 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
29650 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
29660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29670 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
29680 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33  mmit Mode {H1293
29690 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S60200>.** K
296a0 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
296b0 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
296c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
296d0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
296e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
296f0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
29700 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
29710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29720 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
29730 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
29740 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
29750 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d  ively.  Autocomm
29760 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
29770 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74   default..** Aut
29780 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
29790 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
297a0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
297b0 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
297c0 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
297d0 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
297e0 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
297f0 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
29800 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
29810 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
29820 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
29830 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
29840 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
29850 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
29860 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
29870 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
29880 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
29890 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
298a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
298b0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
298c0 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
298d0 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
298e0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
298f0 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
29900 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
29910 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
29920 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
29930 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
29940 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
29950 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
29960 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
29970 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
29980 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
29990 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
299a0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
299b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
299c0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
299d0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
299e0 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
299f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
29a00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
29a10 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29a20 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 32  s: [H12931] [H12
29a30 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48  932] [H12933] [H
29a40 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  12934].*/.int sq
29a50 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
29a60 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
29a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29a80 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
29a90 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
29aa0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29ab0 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36  t {H13120} <S606
29ac0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
29ad0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
29ae0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29af0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
29b00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
29b10 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
29b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29b30 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
29b40 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
29b50 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
29b60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
29b70 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
29b80 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
29b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
29ba0 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
29bb0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
29bc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
29bd0 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
29be0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
29bf0 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
29c00 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
29c10 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
29c20 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
29c30 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
29c40 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 71  : [H13123].*/.sq
29c50 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
29c60 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
29c70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29c80 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
29c90 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
29ca0 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   statement {H131
29cb0 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  40} <S60600>.**.
29cc0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
29cd0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
29ce0 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
29cf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29d00 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
29d10 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
29d20 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
29d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
29d40 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
29d50 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
29d60 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
29d70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29d80 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
29d90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
29da0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
29db0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
29dc0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49  nnection pDb.  I
29dd0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
29de0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
29df0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
29e00 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
29e10 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
29e20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
29e30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29e40 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
29e50 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
29e60 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
29e70 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
29e80 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
29e90 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
29ea0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
29eb0 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
29ec0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
29ed0 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  er..**.** Requir
29ee0 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 5d  ements: [H13143]
29ef0 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31 34   [H13146] [H1314
29f00 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 73  9] [H13152].*/.s
29f10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
29f20 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
29f30 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
29f40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29f60 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
29f70 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
29f80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
29f90 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e  H12950} <S60400>
29fa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
29fb0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
29fc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
29fd0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
29fe0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
29ff0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2a000 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2a010 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
2a020 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79  mmitted]..** Any
2a030 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2a040 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2a050 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2a060 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2a070 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2a080 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2a090 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2a0a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
2a0b0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
2a0c0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2a0d0 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2a0e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2a0f0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2a100 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2a110 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
2a120 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20  d back]..** Any 
2a130 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2a140 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2a150 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
2a160 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
2a170 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2a180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2a190 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
2a1a0 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
2a1b0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
2a1c0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
2a1d0 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ck..** If the ca
2a1e0 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2a1f0 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2a200 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2a210 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
2a220 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
2a230 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
2a240 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
2a250 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
2a260 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
2a270 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
2a280 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
2a290 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
2a2a0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
2a2b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ned..**.** The c
2a2c0 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
2a2d0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2a2e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2a2f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2a300 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2a310 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2a320 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
2a330 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2a340 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2a350 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a360 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2a370 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2a380 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2a390 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2a3a0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2a3b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2a3c0 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
2a3d0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2a3e0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2a3f0 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
2a400 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a410 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a420 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2a430 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2a440 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a450 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2a460 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2a470 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2a480 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  aph..**.** Regis
2a490 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2a4a0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2a4b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2a4c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f 6d  .** When the com
2a4d0 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
2a4e0 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
2a4f0 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
2a500 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
2a510 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
2a520 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
2a530 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d 69  y.  If the commi
2a540 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
2a550 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
2a560 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
2a570 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2a580 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
2a590 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   The rollback ho
2a5a0 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
2a5b0 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
2a5c0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
2a5d0 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
2a5e0 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
2a5f0 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
2a600 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
2a610 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
2a620 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
2a630 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2a640 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2a650 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2a660 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2a670 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2a680 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2a690 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2a6a0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2a6b0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2a6c0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2a6d0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2a6e0 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
2a6f0 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2a700 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2a710 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2a720 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2a730 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2a740 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2a750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a760 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2a770 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2a780 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2a790 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2a7a0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
2a7b0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2a7c0 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
2a7d0 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
2a7e0 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
2a7f0 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
2a800 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  todo>.**.** See 
2a810 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2a820 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
2a830 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2a840 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
2a850 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32  ** [H12951] [H12
2a860 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48  952] [H12953] [H
2a870 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a  12954] [H12955].
2a880 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32  ** [H12961] [H12
2a890 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48  962] [H12963] [H
2a8a0 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12964].*/.void *
2a8b0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2a8c0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
2a8d0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
2a8e0 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
2a8f0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2a900 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
2a910 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
2a920 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a930 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
2a940 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2a950 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d  llbacks {H12970}
2a960 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
2a970 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2a980 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2a990 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2a9a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2a9b0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2a9c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a9d0 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2a9e0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2a9f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2aa00 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2aa10 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2aa20 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2aa30 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
2aa40 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2aa50 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2aa60 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2aa70 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2aa80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2aa90 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2aaa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2aab0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2aac0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2aad0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2aae0 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2aaf0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2ab00 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2ab10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2ab20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2ab30 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2ab40 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2ab50 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2ab60 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2ab70 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
2ab80 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
2ab90 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2aba0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2abb0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
2abc0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
2abd0 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
2abe0 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
2abf0 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
2ac00 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
2ac10 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
2ac20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2ac30 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2ac40 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2ac50 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2ac60 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2ac70 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2ac80 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2ac90 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2aca0 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
2acb0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2acc0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
2acd0 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20   the row..** In 
2ace0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2acf0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2ad00 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2ad10 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2ad20 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
2ad30 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2ad40 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
2ad50 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
2ad60 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
2ad70 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
2ad80 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
2ad90 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
2ada0 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  e)..**.** In the
2adb0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2adc0 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
2add0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
2ade0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
2adf0 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
2ae00 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
2ae10 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
2ae20 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
2ae30 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
2ae40 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20 69  ] clause.  Nor i
2ae50 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
2ae60 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
2ae70 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2ae80 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
2ae90 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
2aea0 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
2aeb0 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
2aec0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2aed0 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
2aee0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
2aef0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
2af00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2af10 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
2af20 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2af30 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2af40 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2af50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2af60 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2af70 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
2af80 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
2af90 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2afa0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2afb0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2afc0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2afd0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2afe0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2aff0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2b000 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2b010 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2b020 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
2b030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b040 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2b050 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2b060 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2b070 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b080 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2b090 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2b0a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2b0b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  aph..**.** If an
2b0c0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
2b0d0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
2b0e0 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
2b0f0 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
2b100 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
2b110 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
2b120 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rned..**.** See 
2b130 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2b140 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
2b150 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
2b160 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
2b170 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2b180 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2b190 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b 48  :.** [H12971] [H
2b1a0 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d 20  12973] [H12975] 
2b1b0 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37 39  [H12977] [H12979
2b1c0 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 39  ] [H12981] [H129
2b1d0 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a  83] [H12986].*/.
2b1e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
2b1f0 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
2b200 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
2b210 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
2b220 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
2b230 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
2b240 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
2b250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b260 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2b270 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
2b280 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
2b290 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45  } <S30900>.** KE
2b2a0 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2b2b0 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
2b2c0 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
2b2d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
2b2e0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2b2f0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2b300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2b310 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2b320 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2b330 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2b340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2b350 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2b360 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2b370 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2b380 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2b390 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2b3a0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2b3b0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2b3c0 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
2b3d0 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
2b3e0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2b3f0 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2b400 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2b410 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2b420 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2b430 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2b440 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2b450 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2b460 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2b470 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2b480 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2b490 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2b4a0 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
2b4b0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
2b4c0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
2b4d0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
2b4e0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2b4f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2b500 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2b510 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
2b520 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
2b530 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
2b540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2b550 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
2b560 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
2b570 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
2b580 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
2b590 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
2b5a0 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
2b5b0 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
2b5c0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
2b5d0 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65  ared cache.  Whe
2b5e0 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
2b5f0 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
2b600 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b610 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
2b620 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
2b630 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
2b640 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
2b650 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
2b660 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b670 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
2b680 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
2b690 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
2b6a0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
2b6b0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2b6c0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
2b6d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
2b6e0 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
2b6f0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2b700 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2b710 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
2b720 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
2b730 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2b740 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
2b750 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
2b760 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
2b770 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
2b780 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
2b790 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
2b7a0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
2b7b0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
2b7c0 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75  Mode].**.** Requ
2b7d0 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 33  irements: [H1033
2b7e0 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 30  1] [H10336] [H10
2b7f0 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 2f  337] [H10339].*/
2b800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2b810 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
2b820 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2b830 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
2b840 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
2b850 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33  ory {H17340} <S3
2b860 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0220>.**.** The 
2b870 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2b880 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2b890 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
2b8a0 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
2b8b0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2b8c0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2b8d0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2b8e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
2b8f0 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
2b900 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
2b910 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
2b920 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
2b930 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
2b940 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2b950 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2b960 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
2b970 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73  ial memory..** s
2b980 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2b990 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2b9a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2b9b0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2b9c0 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2b9d0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2b9e0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2b9f0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
2ba00 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2ba10 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33  : [H17341] [H173
2ba20 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  42].*/.int sqlit
2ba30 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2ba40 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
2ba50 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
2ba60 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
2ba70 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53  Size {H17350} <S
2ba80 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2ba90 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2baa0 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2bab0 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2bac0 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2bad0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2bae0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2baf0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2bb00 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49   by SQLite..** I
2bb10 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
2bb20 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
2bb30 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64  ested that would
2bb40 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73   exceed the.** s
2bb50 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20  oft heap limit, 
2bb60 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2bb70 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e  _memory()] is in
2bb80 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20  voked one or.** 
2bb90 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72  more times to fr
2bba0 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65  ee up some space
2bbb0 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f   before the allo
2bbc0 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  cation is perfor
2bbd0 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  med..**.** The l
2bbe0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2bbf0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
2bc00 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
2bc10 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20  se_memory()].** 
2bc20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66  cannot free suff
2bc30 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
2bc40 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
2bc50 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
2bc60 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
2bc70 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
2bc80 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
2bc90 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
2bca0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
2bcb0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
2bcc0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2bcd0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2bce0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2bcf0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2bd00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2bd10 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2bd20 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2bd30 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2bd40 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
2bd50 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2bd60 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2bd70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2bd80 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
2bd90 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2bda0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2bdb0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2bdc0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2bdd0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2bde0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2bdf0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2be00 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2be10 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2be20 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
2be30 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2be40 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2be50 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2be60 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2be70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2be80 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2be90 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2bea0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2beb0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2bec0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2bed0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2bee0 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2bef0 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2bf00 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2bf10 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2bf20 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2bf30 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2bf40 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2bf50 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2bf60 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2bf70 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2bf80 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2bf90 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2bfa0 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2bfb0 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2bfc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2bfd0 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2bfe0 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2bff0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2c000 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2c010 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2c020 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2c030 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  ual threads..**.
2c040 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2c050 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31  .** [H16351] [H1
2c060 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b  6352] [H16353] [
2c070 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d  H16354] [H16355]
2c080 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69   [H16358].*/.voi
2c090 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
2c0a0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
2c0b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c0c0 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
2c0d0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
2c0e0 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32   Of A Table {H12
2c0f0 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a  850} <S60300>.**
2c100 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2c110 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
2c120 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
2c130 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
2c140 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
2c150 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
2c160 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
2c170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c180 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
2c190 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
2c1a0 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
2c1b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2c1c0 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
2c1d0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
2c1e0 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
2c1f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2c200 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
2c210 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
2c220 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
2c230 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
2c240 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2c250 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
2c260 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
2c270 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
2c280 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
2c290 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
2c2a0 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
2c2b0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
2c2c0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2c2d0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
2c2e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
2c2f0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
2c300 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
2c310 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2c320 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
2c330 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2c340 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2c350 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
2c360 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
2c370 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2c380 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
2c390 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
2c3a0 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
2c3b0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
2c3c0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
2c3d0 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
2c3e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
2c3f0 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
2c400 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 65  * Metadata is re
2c410 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
2c420 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
2c430 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
2c440 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
2c450 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
2c460 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2c470 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
2c480 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2c490 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2c4a0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2c4b0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2c4c0 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2c4d0 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2c4e0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
2c4f0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2c500 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2c510 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2c520 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2c530 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2c540 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2c550 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2c560 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2c570 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2c580 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2c590 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2c5a0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2c5b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c5c0 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2c5d0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2c5e0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2c5f0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2c600 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2c610 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2c620 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2c630 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2c640 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2c650 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2c660 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2c670 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2c680 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2c690 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2c6a0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2c6b0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2c6c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
2c6d0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2c6e0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2c6f0 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2c700 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2c710 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2c720 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2c730 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2c740 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2c750 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2c760 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2c770 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2c780 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2c790 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
2c7a0 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65  ly a view, an [e
2c7b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2c7c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
2c7d0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2c7e0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2c7f0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2c800 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2c810 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2c820 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2c830 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2c840 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2c850 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2c860 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2c870 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2c880 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2c890 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20  mn. If there is 
2c8a0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
2c8b0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
2c8c0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
2c8d0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
2c8e0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
2c8f0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
2c900 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
2c910 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
2c920 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
2c930 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
2c940 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
2c950 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
2c960 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
2c970 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
2c980 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
2c990 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
2c9a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2c9b0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
2c9c0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
2c9d0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
2c9e0 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
2c9f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2ca00 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
2ca10 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
2ca20 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
2ca30 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
2ca40 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
2ca50 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2ca60 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
2ca70 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
2ca80 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
2ca90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2caa0 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
2cab0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
2cac0 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a  errmsg())..**.**
2cad0 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c   This API is onl
2cae0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2caf0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2cb00 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2cb10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2cb20 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2cb30 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2cb40 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2cb50 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2cb60 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2cb70 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2cb80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cb90 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2cba0 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2cbb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2cbc0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2cbd0 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2cbe0 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2cbf0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2cc00 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2cc10 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2cc20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2cc30 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2cc40 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2cc50 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2cc60 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2cc70 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2cc80 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2cc90 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2cca0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2ccb0 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2ccc0 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2ccd0 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2cce0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2ccf0 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2cd00 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2cd10 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2cd20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2cd30 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2cd40 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2cd50 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2cd60 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2cd70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cd80 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2cd90 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2cda0 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2cdb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cdc0 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2cdd0 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30  on {H12600} <S20
2cde0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2cdf0 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20  interface loads 
2ce00 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
2ce10 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d  ion library from
2ce20 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e   the named file.
2ce30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20  .**.** {H12601} 
2ce40 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2ce50 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2ce60 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2ce70 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20  to load an.**   
2ce80 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78         SQLite ex
2ce90 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
2cea0 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
2ceb0 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
2cec0 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20  ** {H12602} The 
2ced0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
2cee0 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  Proc..**.** {H12
2cef0 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62  603} zProc may b
2cf00 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
2cf10 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
2cf20 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
2cf30 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
2cf40 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2cf50 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2cf60 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20  .**.** {H12604} 
2cf70 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2cf80 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2cf90 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74  erface shall ret
2cfa0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2cfb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2cfc0 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
2cfd0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
2cfe0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2cff0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35  g..**.** {H12605
2d000 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  } If an error oc
2d010 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
2d020 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
2d030 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d040 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2d050 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2d060 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2d070 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  mpt to.**       
2d080 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73     fill *pzErrMs
2d090 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
2d0a0 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
2d0b0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   in memory.**   
2d0c0 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
2d0d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d0e0 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20  lloc()]. {END}  
2d0f0 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
2d100 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2d110 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2d120 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2d130 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2d140 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
2d150 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c  606} Extension l
2d160 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
2d170 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
2d180 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d190 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2d1a0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2d1b0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2d1c0 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20   API,.**        
2d1d0 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65    otherwise an e
2d1e0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
2d1f0 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
2d200 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2d210 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
2d220 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
2d230 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
2d240 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
2d250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d260 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2d270 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
2d280 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
2d290 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
2d2a0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
2d2b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d2c0 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
2d2d0 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
2d2e0 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
2d2f0 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
2d300 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
2d310 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
2d320 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
2d330 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
2d340 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2d350 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
2d360 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31  sion Loading {H1
2d370 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a  2620} <S20500>.*
2d380 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
2d390 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
2d3a0 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
2d3b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2d3c0 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
2d3d0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
2d3e0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
2d3f0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
2d400 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
2d410 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
2d420 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
2d430 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
2d440 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
2d450 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
2d460 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
2d470 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
2d480 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
2d490 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
2d4a0 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e  off..**.** Exten
2d4b0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
2d4c0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
2d4d0 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
2d4e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d  ..**.** {H12621}
2d4f0 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65   Call the sqlite
2d500 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2d510 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
2d520 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
2d530 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
2d540 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
2d550 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
2d560 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
2d570 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20  =0 to turn.**   
2d580 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f         it back o
2d590 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20  ff again..**.** 
2d5a0 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69  {H12622} Extensi
2d5b0 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66  on loading is of
2d5c0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f  f by default..*/
2d5d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2d5e0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2d5f0 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  on(sqlite3 *db, 
2d600 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
2d610 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
2d620 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
2d630 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48  An Extensions {H
2d640 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12640} <S20500>.
2d650 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
2d660 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
2d670 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
2d680 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
2d690 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
2d6a0 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
2d6b0 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
2d6c0 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
2d6d0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
2d6e0 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ll new [database
2d6f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b   connections]. {
2d700 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
2d710 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
2d720 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d730 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
2d740 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a  array that is.**
2d750 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2d760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2d770 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61  ].  If you run a
2d780 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65   memory leak che
2d790 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20  cker.** on your 
2d7a0 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72  program and it r
2d7b0 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65  eports a leak be
2d7c0 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 72  cause of this ar
2d7d0 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  ray, invoke.** [
2d7e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
2d7f0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
2d800 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77  prior to shutdow
2d810 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
2d820 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  mory..**.** {H12
2d830 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  641} This functi
2d840 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  on registers an 
2d850 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
2d860 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a  point that is.**
2d870 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
2d880 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
2d890 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
2d8a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d8b0 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion].**         
2d8c0 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67   is opened using
2d8d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2d8e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2d8f0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
2d900 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
2d910 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
2d920 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63   {H12642} Duplic
2d930 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
2d940 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
2d950 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
2d960 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ine.**          
2d970 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
2d980 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
2d990 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
2d9a0 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34  ss..**.** {H1264
2d9b0 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  3} This routine 
2d9c0 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
2d9d0 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
2d9e0 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a  n in an array.**
2d9f0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
2da00 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2da10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2da20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34  )]..**.** {H1264
2da30 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74  4} Automatic ext
2da40 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
2da50 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
2da60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2da70 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2da80 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69  void (*xEntryPoi
2da90 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a  nt)(void));../*.
2daa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2dab0 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
2dac0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
2dad0 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e  H12660} <S20500>
2dae0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
2daf0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
2db00 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
2db10 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69  istered automati
2db20 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e  c.** extensions.
2db30 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65   {END}  It undoe
2db40 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
2db50 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71  all prior.** [sq
2db60 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
2db70 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a  sion()] calls..*
2db80 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68  *.** {H12661} Th
2db90 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
2dba0 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
2dbb0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a  sly registered.*
2dbc0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2dbd0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
2dbe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20  .**.** {H12662} 
2dbf0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2dc00 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
2dc10 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
2dc20 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
2dc30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
2dc40 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2dc50 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a  (void);../*.****
2dc60 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
2dc70 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
2dc80 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
2dc90 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
2dca0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
2dcb0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
2dcc0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2dcd0 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
2dce0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
2dcf0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
2dd00 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
2dd10 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
2dd20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
2dd30 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
2dd40 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
2dd50 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
2dd60 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
2dd70 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
2dd80 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
2dd90 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
2dda0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
2ddb0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
2ddc0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
2ddd0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
2dde0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
2ddf0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
2de00 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
2de10 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
2de20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
2de30 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
2de40 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
2de50 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2de60 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
2de70 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2de80 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2de90 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
2dea0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
2deb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
2dec0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
2ded0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
2dee0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2def0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
2df00 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
2df10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
2df20 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
2df30 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 30  ct {H18000} <S20
2df40 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
2df50 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
2df60 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
2df70 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52  module}.** EXPER
2df80 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
2df90 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f  is structure, so
2dfa0 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61  metimes called a
2dfb0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
2dfc0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
2dfd0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
2dfe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
2dff0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
2e000 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
2e010 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
2e020 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
2e030 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
2e040 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
2e050 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20  table module is 
2e060 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69  created by filli
2e070 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65  ng in a persiste
2e080 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  nt.** instance o
2e090 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
2e0a0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70   and passing a p
2e0b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69  ointer to that i
2e0c0 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73  nstance.** to [s
2e0d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2e0e0 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  dule()] or [sqli
2e0f0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2e100 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
2e110 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
2e120 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
2e130 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
2e140 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
2e150 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
2e160 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
2e170 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
2e180 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
2e190 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
2e1a0 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
2e1b0 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
2e1c0 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
2e1d0 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
2e1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
2e1f0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
2e200 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
2e210 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
2e220 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
2e230 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
2e240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2e250 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
2e260 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
2e270 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e280 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
2e290 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
2e2a0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
2e2b0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
2e2c0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
2e2d0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2e2e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
2e2f0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
2e300 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
2e310 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
2e320 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
2e330 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
2e340 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2e350 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2e360 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
2e370 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
2e380 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2e390 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
2e3a0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
2e3b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2e3c0 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
2e3d0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2e3e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2e3f0 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
2e400 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
2e410 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2e420 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
2e430 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
2e440 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
2e450 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
2e460 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
2e470 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2e480 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
2e490 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
2e4a0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
2e4b0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2e4c0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
2e4d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2e4e0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2e4f0 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
2e500 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2e510 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e520 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
2e530 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
2e540 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
2e550 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
2e560 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
2e570 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
2e580 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
2e590 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
2e5a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
2e5b0 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
2e5c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2e5d0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
2e5e0 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
2e5f0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e600 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
2e610 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2e620 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
2e630 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
2e640 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e650 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
2e660 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2e670 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
2e680 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2e690 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
2e6a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
2e6b0 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
2e6c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e6e0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e6f0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
2e700 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
2e710 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
2e720 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
2e730 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
2e740 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
2e750 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
2e760 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
2e770 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d  rmation {H18100}
2e780 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2e790 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
2e7a0 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50  ndex_info.** EXP
2e7b0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2e7c0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
2e7d0 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
2e7e0 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
2e7f0 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74  ctures is used t
2e800 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
2e810 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
2e820 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
2e830 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74   from the [xBest
2e840 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64  Index].** method
2e850 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
2e860 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54  able module].  T
2e870 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
2e880 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
2e890 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
2e8a0 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
2e8b0 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
2e8c0 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
2e8d0 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
2e8e0 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
2e8f0 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
2e900 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
2e910 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
2e920 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
2e930 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
2e940 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
2e950 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  <pre>column OP e
2e960 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  xpr</pre>.**.** 
2e970 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
2e980 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
2e990 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 65  , or &gt;=.  The
2e9a0 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
2e9b0 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
2e9c0 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
2e9d0 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
2e9e0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2e9f0 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
2ea00 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
2ea10 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
2ea20 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
2ea30 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
2ea40 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
2ea50 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
2ea60 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
2ea70 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
2ea80 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
2ea90 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
2eaa0 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
2eab0 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
2eac0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2ead0 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
2eae0 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
2eaf0 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
2eb00 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
2eb10 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
2eb20 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
2eb30 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
2eb40 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
2eb50 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
2eb60 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
2eb70 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
2eb80 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
2eb90 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
2eba0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
2ebb0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
2ebc0 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
2ebd0 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
2ebe0 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
2ebf0 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
2ec00 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
2ec10 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
2ec20 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2ec30 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2ec40 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
2ec50 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
2ec60 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
2ec70 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
2ec80 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
2ec90 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
2eca0 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65  * The [xBestInde
2ecb0 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  x] method must f
2ecc0 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
2ecd0 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
2ece0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
2ecf0 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
2ed00 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
2ed10 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64  ter.  If argvInd
2ed20 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
2ed30 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2ed40 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
2ed50 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
2ed60 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
2ed70 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
2ed80 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
2ed90 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
2eda0 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55   If aConstraintU
2edb0 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
2edc0 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
2edd0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
2ede0 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
2edf0 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
2ee00 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
2ee10 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
2ee20 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
2ee30 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2ee40 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
2ee50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
2ee60 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
2ee70 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
2ee80 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
2ee90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2eea0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
2eeb0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
2eec0 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65  d only iff.** ne
2eed0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
2eee0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s true..**.** Th
2eef0 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
2ef00 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
2ef10 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
2ef20 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
2ef30 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
2ef40 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
2ef50 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
2ef60 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
2ef70 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
2ef80 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
2ef90 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2efa0 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
2efb0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
2efc0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
2efd0 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
2efe0 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
2eff0 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
2f000 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
2f010 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
2f020 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
2f030 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
2f040 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
2f050 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
2f060 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
2f070 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
2f080 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
2f090 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
2f0a0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
2f0b0 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
2f0c0 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72  */.  int nConstr
2f0d0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
2f0e0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
2f0f0 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
2f100 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  int */.  struct 
2f110 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
2f120 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20  nstraint {.     
2f130 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
2f140 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
2f150 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64  umn on left-hand
2f160 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61   side of constra
2f170 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  int */.     unsi
2f180 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20  gned char op;   
2f190 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61        /* Constra
2f1a0 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a  int operator */.
2f1b0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
2f1c0 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f  ar usable;     /
2f1d0 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63  * True if this c
2f1e0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61  onstraint is usa
2f1f0 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20  ble */.     int 
2f200 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20  iTermOffset;    
2f210 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
2f220 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74  ternally - xBest
2f230 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e  Index should ign
2f240 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  ore */.  } *aCon
2f250 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
2f260 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20      /* Table of 
2f270 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
2f280 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e  straints */.  in
2f290 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
2f2a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
2f2b0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74  er of terms in t
2f2c0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2f2d0 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  se */.  struct s
2f2e0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
2f2f0 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20  erby {.     int 
2f300 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
2f310 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
2f320 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75  number */.     u
2f330 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73  nsigned char des
2f340 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  c;       /* True
2f350 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73   for DESC.  Fals
2f360 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20  e for ASC. */.  
2f370 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20  } *aOrderBy;    
2f380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68             /* Th
2f390 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2f3a0 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74  e */.  /* Output
2f3b0 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  s */.  struct sq
2f3c0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
2f3d0 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20  traint_usage {. 
2f3e0 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78     int argvIndex
2f3f0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69  ;           /* i
2f400 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74  f >0, constraint
2f410 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76   is part of argv
2f420 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20   to xFilter */. 
2f430 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
2f440 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44   omit;      /* D
2f450 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73  o not code a tes
2f460 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74  t for this const
2f470 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43  raint */.  } *aC
2f480 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
2f490 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
2f4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f4b0 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
2f4c0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
2f4d0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
2f4e0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
2f4f0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
2f500 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
2f510 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
2f520 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
2f530 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
2f540 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
2f550 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
2f560 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
2f570 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
2f580 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
2f590 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
2f5a0 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
2f5b0 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
2f5c0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
2f5d0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
2f5e0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
2f5f0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
2f600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f610 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
2f620 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
2f630 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
2f640 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
2f650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f660 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
2f670 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
2f680 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
2f690 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
2f6a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f6b0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
2f6c0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
2f6d0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2f6e0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
2f6f0 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  64../*.** CAPI3R
2f700 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56  EF: Register A V
2f710 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70  irtual Table Imp
2f720 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38  lementation {H18
2f730 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  200} <S20400>.**
2f740 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2f750 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2f760 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69   is used to regi
2f770 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74  ster a new [virt
2f780 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2f790 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 6c  ] name..** Modul
2f7a0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
2f7b0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
2f7c0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
2f7d0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
2f7e0 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
2f7f0 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
2f800 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
2f810 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
2f820 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
2f830 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  odule..**.** The
2f840 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20   module name is 
2f850 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68  registered on th
2f860 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f870 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2f880 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
2f890 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  t parameter.  Th
2f8a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  e name of the mo
2f8b0 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79  dule is given by
2f8c0 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20   the .** second 
2f8d0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
2f8e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f8f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
2f900 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2f910 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69  ation of the [vi
2f920 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2f930 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72 74  le].   The fourt
2f940 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  h.** parameter i
2f950 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63  s an arbitrary c
2f960 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
2f970 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
2f980 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74  d through.** int
2f990 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20  o the [xCreate] 
2f9a0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
2f9b0 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69  ethods of the vi
2f9c0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2f9d0 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77  le.** when a new
2f9e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
2f9f0 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74  s be being creat
2fa00 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69  ed or reinitiali
2fa10 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  zed..**.** This 
2fa20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65 78  interface has ex
2fa30 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 65  actly the same e
2fa40 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e 67  ffect as calling
2fa50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2fa60 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
2fa70 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c 69   with a NULL cli
2fa80 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75 63  ent data destruc
2fa90 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  tor..*/.SQLITE_E
2faa0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
2fab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2fac0 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
2fad0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2fae0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
2faf0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
2fb00 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
2fb10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2fb20 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
2fb30 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2fb40 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
2fb50 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2fb60 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
2fb70 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
2fb80 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
2fb90 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
2fba0 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
2fbb0 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
2fbc0 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  nect */.);../*.*
2fbd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
2fbe0 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54  ster A Virtual T
2fbf0 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74  able Implementat
2fc00 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 32  ion {H18210} <S2
2fc10 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
2fc20 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
2fc30 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
2fc40 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 71  tical to the [sq
2fc50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2fc60 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a  ule()] method,.*
2fc70 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
2fc80 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70 61   has an extra pa
2fc90 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63 69  rameter to speci
2fca0 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75 63  fy .** a destruc
2fcb0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
2fcc0 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74 61   the client data
2fcd0 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69 74   pointer.  SQLit
2fce0 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65  e will.** invoke
2fcf0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2fd00 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20  function (if it 
2fd10 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65  is not NULL) whe
2fd20 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c  n SQLite.** no l
2fd30 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20  onger needs the 
2fd40 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e  pClientData poin
2fd50 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45  ter.  .*/.SQLITE
2fd60 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
2fd70 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2fd80 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
2fd90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fda0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
2fdb0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
2fdc0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
2fdd0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
2fde0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
2fdf0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
2fe00 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
2fe10 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
2fe20 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
2fe30 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2fe40 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
2fe50 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
2fe60 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
2fe70 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
2fe80 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
2fe90 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2fea0 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
2feb0 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
2fec0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
2fed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2fee0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
2fef0 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 31  tance Object {H1
2ff00 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8010} <S20400>.*
2ff10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2ff20 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45  te3_vtab.** EXPE
2ff30 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45  RIMENTAL.**.** E
2ff40 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
2ff50 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
2ff60 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
2ff70 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
2ff80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2ff90 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63  tructure to desc
2ffa0 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
2ffb0 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
2ffc0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
2ffd0 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
2ffe0 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
2fff0 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
30000 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
30010 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
30020 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
30030 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
30040 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
30050 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
30060 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
30070 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
30080 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
30090 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
300a0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
300b0 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
300c0 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
300d0 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
300e0 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
300f0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
30100 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
30110 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
30120 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
30130 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
30140 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
30150 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
30160 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
30170 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
30180 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
30190 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
301a0 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
301b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
301c0 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
301d0 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
301e0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
301f0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
30200 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
30210 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
30220 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
30230 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
30240 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a  ill be zeroed..*
30250 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
30260 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20  _vtab {.  const 
30270 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
30280 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65  pModule;  /* The
30290 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73   module for this
302a0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a   virtual table *
302b0 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20  /.  int nRef;   
302c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
302d0 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
302e0 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72  rnally */.  char
302f0 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
30300 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
30310 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
30320 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
30330 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
30340 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
30350 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
30360 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
30370 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
30380 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
30390 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
303a0 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
303b0 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30  t  {H18020} <S20
303c0 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
303d0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
303e0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
303f0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20  able cursor}.** 
30400 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
30410 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
30420 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
30430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
30440 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
30450 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
30460 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
30470 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
30480 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
30490 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
304a0 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
304b0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
304c0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
304d0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
304e0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
304f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
30500 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
30510 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
30520 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
30530 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
30540 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
30550 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
30560 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
30570 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 61  thod.  Cussors a
30580 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
30590 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
305a0 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
305b0 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
305c0 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
305d0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
305e0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
305f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
30600 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
30610 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
30620 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
30630 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
30640 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
30650 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
30660 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
30670 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
30680 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
30690 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
306a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
306b0 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
306c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
306d0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
306e0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
306f0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
30700 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
30710 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
30720 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
30730 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
30740 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
30750 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
30760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30770 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
30780 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
30790 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d  l Table {H18280}
307a0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
307b0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
307c0 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
307d0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
307e0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
307f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30800 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
30810 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
30820 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
30830 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
30840 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
30850 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
30860 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
30870 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
30880 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  t..*/.SQLITE_EXP
30890 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
308a0 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
308b0 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
308c0 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
308d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
308e0 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
308f0 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
30900 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30  al Table {H18300
30910 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
30920 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
30930 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
30940 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
30950 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
30960 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
30970 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
30980 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
30990 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
309a0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
309b0 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
309c0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
309d0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
309e0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
309f0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
30a00 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
30a10 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
30a20 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
30a30 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
30a40 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
30a50 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
30a60 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
30a70 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
30a80 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
30a90 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
30aa0 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
30ab0 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
30ac0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
30ad0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
30ae0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
30af0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
30b00 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
30b10 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
30b20 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
30b30 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
30b40 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
30b50 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
30b60 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
30b70 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
30b80 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
30b90 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
30ba0 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
30bb0 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
30bc0 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51  al table]..*/.SQ
30bd0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
30be0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  L int sqlite3_ov
30bf0 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
30c00 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
30c10 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
30c20 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
30c30 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
30c40 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
30c50 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
30c60 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
30c70 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
30c80 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
30c90 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
30ca0 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
30cb0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
30cc0 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
30cd0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
30ce0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
30cf0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
30d00 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
30d10 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
30d20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
30d30 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
30d40 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
30d50 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
30d60 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
30d70 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
30d80 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
30d90 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
30da0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
30db0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
30dc0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
30dd0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
30de0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
30df0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
30e00 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
30e10 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
30e20 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
30e30 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
30e40 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
30e50 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30  OB {H17800} <S30
30e60 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  230>.** KEYWORDS
30e70 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
30e80 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
30e90 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
30ea0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
30eb0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
30ec0 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
30ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
30ee0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
30ef0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
30f00 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
30f10 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
30f20 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
30f30 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
30f40 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
30f50 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
30f60 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
30f70 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
30f80 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
30f90 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
30fa0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
30fb0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
30fc0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
30fd0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
30fe0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
30ff0 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54  f the BLOB..** T
31000 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
31010 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
31020 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
31030 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
31040 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
31050 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
31060 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
31070 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
31080 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
31090 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
310a0 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30  ntal I/O {H17810
310b0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
310c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73   This interfaces
310d0 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
310e0 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
310f0 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
31100 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
31110 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
31120 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
31130 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
31140 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
31150 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
31160 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
31170 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
31180 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
31190 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
311a0 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
311b0 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
311c0 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
311d0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
311e0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
311f0 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
31200 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
31210 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
31220 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
31230 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
31240 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ero, the BLOB is
31250 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
31260 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e   access..**.** N
31270 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
31280 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
31290 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
312a0 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
312b0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
312c0 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
312d0 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
312e0 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
312f0 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68  * is assigned wh
31300 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
31310 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
31320 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
31330 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
31340 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
31350 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
31360 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20   "main"..** For 
31370 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
31380 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
31390 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
313a0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
313b0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
313c0 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
313d0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73  [BLOB handle] is
313e0 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a   written.** to *
313f0 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73  ppBlob. Otherwis
31400 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
31410 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
31420 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74  d *ppBlob is set
31430 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c  .** to be a null
31440 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69   pointer..** Thi
31450 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
31460 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
31470 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
31480 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
31490 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
314a0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
314b0 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
314c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
314d0 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
314e0 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68  ctions.  Note th
314f0 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76  at the *ppBlob v
31500 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79  ariable is alway
31510 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e  s initialized in
31520 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d   a.** way that m
31530 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20  akes it safe to 
31540 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
31550 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e  blob_close()] on
31560 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61   *ppBlob.** rega
31570 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
31580 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
31590 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
315a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
315b0 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
315c0 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
315d0 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
315e0 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
315f0 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
31600 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
31610 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
31620 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
31630 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
31640 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
31650 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
31660 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
31670 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
31680 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
31690 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
316a0 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
316b0 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a  le is open on..*
316c0 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * Calls to [sqli
316d0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
316e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
316f0 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
31700 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
31710 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
31720 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
31730 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
31740 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20  RT]..** Changes 
31750 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
31760 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
31770 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
31780 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61  re not.** rollba
31790 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
317a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
317b0 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
317c0 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
317d0 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
317e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
317f0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
31800 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20  tion..**.** Use 
31810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
31820 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
31830 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  face to determin
31840 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  e the size of.**
31850 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62   the opened blob
31860 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61  .  The size of a
31870 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
31880 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
31890 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 2e 20 20  .** underface.  
318a0 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
318b0 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
318c0 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
318d0 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
318e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
318f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
31900 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
31910 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
31920 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
31930 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
31940 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
31950 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
31960 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
31970 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
31980 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
31990 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
319a0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
319b0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
319c0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
319d0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
319e0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
319f0 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
31a00 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
31a10 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
31a20 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
31a30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
31a40 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  b_close()]..**.*
31a50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
31a60 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37  ** [H17813] [H17
31a70 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48  814] [H17816] [H
31a80 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20  17819] [H17821] 
31a90 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20  [H17824].*/.int 
31aa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
31ab0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
31ac0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
31ad0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31ae0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
31af0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
31b00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
31b10 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
31b20 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
31b30 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
31b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
31b50 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
31b60 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32  e {H17830} <S302
31b70 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73  30>.**.** Closes
31b80 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
31b90 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c  andle]..**.** Cl
31ba0 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61  osing a BLOB sha
31bb0 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72  ll cause the cur
31bc0 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
31bd0 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66   to commit.** if
31be0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74   there are no ot
31bf0 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65  her BLOBs, no pe
31c00 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73  nding prepared s
31c10 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74  tatements, and t
31c20 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
31c30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
31c40 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  [autocommit mode
31c50 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69  ]..** If any wri
31c60 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
31c70 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
31c80 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
31c90 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
31ca0 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
31cb0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
31cc0 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73   fit..**.** Clos
31cd0 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74  ing the BLOB oft
31ce0 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68  en forces the ch
31cf0 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20  anges.** out to 
31d00 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61  disk and so if a
31d10 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63  ny I/O errors oc
31d20 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c  cur, they will l
31d30 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61  ikely occur.** a
31d40 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
31d50 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  the BLOB is clos
31d60 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20  ed.  Any errors 
31d70 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e  that occur durin
31d80 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65  g.** closing are
31d90 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e   reported as a n
31da0 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76  on-zero return v
31db0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
31dc0 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
31dd0 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
31de0 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
31df0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
31e00 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
31e10 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
31e20 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  l closed..**.** 
31e30 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
31e40 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
31e50 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20   pointer (which 
31e60 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  as would be retu
31e70 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65  rned.** by faile
31e80 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
31e90 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
31ea0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
31eb0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  o-op..**.** Requ
31ec0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
31ed0 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b  7833] [H17836] [
31ee0 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H17839].*/.int s
31ef0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
31f00 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
31f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31f20 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53  EF: Return The S
31f30 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
31f40 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33  LOB {H17840} <S3
31f50 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0230>.**.** Retu
31f60 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20  rns the size in 
31f70 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f  bytes of the BLO
31f80 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  B accessible via
31f90 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73   the .** success
31fa0 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c  fully opened [BL
31fb0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74  OB handle] in it
31fc0 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  s only argument.
31fd0 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65    The.** increme
31fe0 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f  ntal blob I/O ro
31ff0 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20  utines can only 
32000 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74  read or overwrit
32010 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  ing existing.** 
32020 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68  blob content; th
32030 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  ey cannot change
32040 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
32050 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lob..**.** This 
32060 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
32070 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
32080 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
32090 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
320a0 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
320b0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
320c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
320d0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
320e0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
320f0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
32100 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
32110 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
32120 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
32130 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
32140 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
32150 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
32160 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
32170 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52  ehavior..**.** R
32180 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
32190 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20  [H17843].*/.int 
321a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
321b0 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
321c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
321d0 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46  REF: Read Data F
321e0 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
321f0 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30  mentally {H17850
32200 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
32210 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
32220 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
32230 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
32240 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
32250 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  nto a.** caller-
32260 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
32270 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
32280 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
32290 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f   buffer Z.** fro
322a0 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  m the open BLOB,
322b0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
322c0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
322d0 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66  ** If offset iOf
322e0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
322f0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
32300 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
32310 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
32320 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
32330 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
32340 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20   read.  If N or 
32350 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
32360 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
32370 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
32380 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
32390 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
323a0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
323b0 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65   blob (and hence
323c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
323d0 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
323e0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
323f0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
32400 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
32410 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
32420 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d  ..**.** An attem
32430 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
32440 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
32450 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
32460 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
32470 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
32480 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ABORT]..**.** On
32490 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
324a0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
324b0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
324c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
324d0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
324e0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
324f0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
32500 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
32510 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
32520 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
32530 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
32540 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
32550 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
32560 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
32570 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
32580 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
32590 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
325a0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
325b0 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
325c0 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
325d0 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
325e0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
325f0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
32600 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
32610 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
32620 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
32630 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
32640 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
32650 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
32660 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31  53] [H17856] [H1
32670 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b  7859] [H17862] [
32680 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d  H17863] [H17865]
32690 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74   [H17868].*/.int
326a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
326b0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
326c0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
326d0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
326e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
326f0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
32700 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
32710 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20  ntally {H17870} 
32720 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30230>.**.** T
32730 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
32740 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
32750 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
32760 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
32770 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
32780 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
32790 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
327a0 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
327b0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
327c0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
327d0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
327e0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
327f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c  **.** If the [BL
32800 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  OB handle] passe
32810 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
32820 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20  rgument was not 
32830 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72  opened for.** wr
32840 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
32850 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
32860 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
32870 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a  ()] was zero),.*
32880 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * this function 
32890 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
328a0 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a  READONLY]..**.**
328b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
328c0 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
328d0 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
328e0 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
328f0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
32900 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
32910 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
32920 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
32930 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
32940 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
32950 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
32960 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
32970 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
32980 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
32990 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
329a0 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73  ritten.  If N is
329b0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
329c0 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
329d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
329e0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
329f0 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
32a00 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
32a10 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
32a20 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
32a30 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
32a40 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
32a50 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
32a60 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
32a70 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
32a80 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
32a90 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
32aa0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
32ab0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
32ac0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
32ad0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
32ae0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c  Writes to the BL
32af0 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64  OB that occurred
32b00 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
32b10 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70  BLOB handle] exp
32b20 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c  ired are not rol
32b30 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a  led back by the.
32b40 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  ** expiration of
32b50 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f   the handle, tho
32b60 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
32b70 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68  ose changes migh
32b80 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f  t.** have been o
32b90 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
32ba0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
32bb0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f   expired the BLO
32bc0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62  B handle.** or b
32bd0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64  y other independ
32be0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  ent statements..
32bf0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
32c00 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
32c10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
32c20 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
32c30 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
32c40 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
32c50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
32c60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
32c70 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
32c80 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
32c90 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
32ca0 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
32cb0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
32cc0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
32cd0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
32ce0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
32cf0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
32d00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
32d10 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
32d20 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
32d30 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
32d40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
32d50 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
32d60 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
32d70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
32d80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
32d90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
32da0 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a  ob_read()]..**.*
32db0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
32dc0 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37  ** [H17873] [H17
32dd0 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48  874] [H17875] [H
32de0 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20  17876] [H17877] 
32df0 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32  [H17879] [H17882
32e00 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48  ] [H17885].** [H
32e10 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17888].*/.int sq
32e20 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
32e30 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
32e40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
32e50 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
32e60 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
32e70 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
32e80 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
32e90 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31  s {H11200} <S201
32ea0 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  00>.**.** A virt
32eb0 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
32ec0 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
32ed0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
32ee0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
32ef0 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
32f00 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
32f10 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
32f20 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
32f30 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
32f40 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
32f50 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
32f60 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
32f70 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
32f80 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
32f90 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
32fa0 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
32fb0 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
32fc0 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
32fd0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
32fe0 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
32ff0 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
33000 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
33010 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
33020 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
33030 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
33040 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
33050 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
33060 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d  ensitive..** Nam
33070 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  es are zero-term
33080 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
33090 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72  ings..** If ther
330a0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
330b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
330c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
330d0 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
330e0 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
330f0 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e  lt VFS is return
33100 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46  ed..**.** New VF
33110 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
33120 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
33130 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
33140 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  ** Each new VFS 
33150 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
33160 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
33170 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
33180 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
33190 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
331a0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
331b0 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
331c0 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
331d0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
331e0 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
331f0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
33200 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
33210 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
33220 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
33230 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
33240 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
33250 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
33260 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
33270 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
33280 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
33290 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
332a0 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
332b0 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
332c0 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
332d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
332e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
332f0 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
33300 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
33310 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
33320 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
33330 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
33340 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
33350 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
33360 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
33370 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
33380 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
33390 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
333a0 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
333b0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
333c0 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30   [H11203] [H1120
333d0 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31  6] [H11209] [H11
333e0 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48  212] [H11215] [H
333f0 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65  11218].*/.sqlite
33400 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
33410 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
33420 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
33430 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
33440 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
33450 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
33460 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
33470 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
33480 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
33490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
334a0 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d  Mutexes {H17000}
334b0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
334c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
334d0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
334e0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
334f0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
33500 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
33510 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
33520 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
33530 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
33540 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
33550 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
33560 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
33570 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
33580 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
33590 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
335a0 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
335b0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
335c0 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
335d0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
335e0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
335f0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
33600 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
33610 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
33620 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
33630 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   The following.*
33640 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
33650 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
33660 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
33670 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
33680 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
33690 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
336a0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
336b0 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
336c0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
336d0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
336e0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
336f0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
33700 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
33710 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
33720 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
33730 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
33740 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
33750 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
33760 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
33770 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
33780 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
33790 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
337a0 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
337b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
337c0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
337d0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
337e0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
337f0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
33800 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55  r use on OS/2, U
33810 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73  nix, and Windows
33820 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ..**.** If SQLit
33830 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
33840 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
33850 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
33860 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
33870 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
33880 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
33890 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
338a0 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
338b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
338c0 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
338d0 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
338e0 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
338f0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
33900 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
33910 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
33920 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
33930 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
33940 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
33950 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
33960 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
33970 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
33980 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
33990 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
339a0 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
339b0 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
339c0 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
339d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
339e0 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68  *.** {H17011} Th
339f0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
33a00 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
33a10 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
33a20 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
33a30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
33a40 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49  o it. {H17012} I
33a50 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
33a60 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
33a70 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
33a80 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
33a90 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51  ted. {H17013} SQ
33aa0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
33ab0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
33ac0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
33ad0 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20  r. {H17014} The 
33ae0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
33af0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
33b00 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
33b10 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
33b20 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
33b30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
33b40 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
33b50 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
33b60 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
33b70 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
33b80 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
33b90 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
33ba0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
33bb0 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
33bc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
33bd0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
33be0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
33bf0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
33c00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
33c10 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
33c20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
33c30 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
33c40 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35  l>.**.** {H17015
33c50 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  } The first two 
33c60 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
33c70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
33c80 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
33c90 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
33ca0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
33cb0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
33cc0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
33cd0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
33ce0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
33cf0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
33d00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
33d10 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a   is used. {END}.
33d20 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
33d30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
33d40 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
33d50 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
33d60 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
33d70 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
33d80 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
33d90 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
33da0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
33db0 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74  o.  {H17016} But
33dc0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
33dd0 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
33de0 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
33df0 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
33e00 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
33e10 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66  e.  {END} If a f
33e20 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
33e30 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
33e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
33e50 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
33e60 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
33e70 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
33e80 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
33e90 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
33ea0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
33eb0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
33ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d  ..**.** {H17017}
33ed0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
33ee0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
33ef0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
33f00 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
33f10 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
33f20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
33f30 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b  xisting mutex. {
33f40 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69  END}  Four stati
33f50 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
33f60 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
33f70 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
33f80 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
33f90 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
33fa0 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
33fb0 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
33fc0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
33fd0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
33fe0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
33ff0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
34000 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
34010 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
34020 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
34030 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
34040 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
34050 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
34060 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
34070 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
34080 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
34090 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68  {H17018} Note th
340a0 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
340b0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
340c0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
340d0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
340e0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
340f0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
34100 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
34110 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
34120 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
34130 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
34140 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30  ery call.  {H170
34150 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20  34} But for the 
34160 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
34170 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
34180 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
34190 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
341a0 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
341b0 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
341c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d  ..**.** {H17019}
341d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
341e0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
341f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
34200 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
34210 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
34220 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20  mutex. {H17020} 
34230 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
34240 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
34250 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
34260 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
34270 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32  llocates. {A1702
34280 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  1} The dynamic m
34290 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
342a0 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65  be in.** use whe
342b0 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c  n they are deall
342c0 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d  ocated. {A17022}
342d0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
342e0 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
342f0 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
34300 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
34310 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30   behavior. {H170
34320 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72  23} SQLite never
34330 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
34340 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20  a static mutex. 
34350 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
34360 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
34370 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
34380 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
34390 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
343a0 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
343b0 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20  ex. {H17024} If 
343c0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69  another thread i
343d0 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e  s already within
343e0 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73   the mutex,.** s
343f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
34400 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20  er() will block 
34410 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
34420 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74  x_try() will ret
34430 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  urn.** SQLITE_BU
34440 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68  SY. {H17025}  Th
34450 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
34460 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
34470 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
34480 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
34490 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b  essful entry.  {
344a0 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20  H17026} Mutexes 
344b0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
344c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
344d0 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65  CURSIVE can be e
344e0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
344f0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
34500 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31  e thread..** {H1
34510 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61  7027} In such ca
34520 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
34530 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
34540 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
34550 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
34560 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
34570 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b  ** can enter.  {
34580 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73  A17028} If the s
34590 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
345a0 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
345b0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
345c0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
345d0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
345e0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
345f0 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69  ** {H17029} SQLi
34600 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
34610 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
34620 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
34630 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
34640 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73  ..**.** Some sys
34650 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
34660 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
34670 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
34680 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
34690 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
346a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
346b0 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
346c0 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
346d0 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
346e0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
346f0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48  SQLITE_BUSY.  {H
34700 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74  17030} The SQLit
34710 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72  e core only ever
34720 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33   uses.** sqlite3
34730 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20  _mutex_try() as 
34740 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  an optimization 
34750 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70  so this is accep
34760 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  table behavior..
34770 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54  **.** {H17031} T
34780 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
34790 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
347a0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
347b0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
347c0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
347d0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
347e0 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20  .  {A17032} The 
347f0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
34800 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
34810 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
34820 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
34830 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
34840 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
34850 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
34860 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d  cated.  {H17033}
34870 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
34880 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
34890 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
348a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
348b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
348c0 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d  ter(), sqlite3_m
348d0 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a  utex_try(), or.*
348e0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
348f0 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c  leave() is a NUL
34900 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
34910 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e  all three routin
34920 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20  es.** behave as 
34930 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  no-ops..**.** Se
34940 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
34950 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61  _mutex_held()] a
34960 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  nd [sqlite3_mute
34970 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f  x_notheld()]..*/
34980 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
34990 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
349a0 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73  loc(int);.void s
349b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
349c0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
349d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
349e0 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69  mutex_enter(sqli
349f0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
34a00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
34a10 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ry(sqlite3_mutex
34a20 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34a30 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c  _mutex_leave(sql
34a40 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
34a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34a60 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a  utex Methods Obj
34a70 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32  ect {H17120} <S2
34a80 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0130>.** EXPERIM
34a90 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ENTAL.**.** An i
34aa0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
34ab0 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65  structure define
34ac0 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  s the low-level 
34ad0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
34ae0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64   to allocate and
34af0 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a   use mutexes..**
34b00 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65  .** Usually, the
34b10 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69   default mutex i
34b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70  mplementations p
34b30 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74  rovided by SQLit
34b40 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69  e are.** suffici
34b50 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65  ent, however the
34b60 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70   user has the op
34b70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75  tion of substitu
34b80 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a  ting a custom.**
34b90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34ba0 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20  for specialized 
34bb0 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73  deployments or s
34bc0 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68  ystems for which
34bd0 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20   SQLite.** does 
34be0 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75  not provide a su
34bf0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
34c00 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63  ation. In this c
34c10 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a  ase, the user.**
34c20 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70   creates and pop
34c30 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e  ulates an instan
34c40 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
34c50 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20  ture to pass.** 
34c60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
34c70 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74  g() along with t
34c80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
34c90 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  G_MUTEX] option.
34ca0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  .** Additionally
34cb0 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  , an instance of
34cc0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
34cd0 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61  can be used as a
34ce0 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69  n.** output vari
34cf0 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
34d00 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f  ng the system fo
34d10 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75  r the current mu
34d20 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
34d30 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65  ation, using the
34d40 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
34d50 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  GETMUTEX] option
34d60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
34d70 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
34d80 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
34d90 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
34da0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
34db0 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
34dc0 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
34dd0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
34de0 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
34df0 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75  {H17001} The xMu
34e00 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
34e10 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20  shall be called 
34e20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66  by SQLite once f
34e30 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63  or each.** effec
34e40 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71  tive call to [sq
34e50 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
34e60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ()]..**.** The x
34e70 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
34e80 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
34e90 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
34ea0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
34eb0 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
34ec0 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
34ed0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
34ee0 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
34ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
34f00 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
34f10 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
34f20 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
34f30 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
34f40 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
34f50 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
34f60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
34f70 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
34f80 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
34f90 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
34fa0 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68  hod. {H17003} Th
34fb0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
34fc0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
34fd0 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   be invoked once
34fe0 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74   for each call t
34ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  o [sqlite3_shutd
35000 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  own()]..**.** Th
35010 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65  e remaining seve
35020 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  n methods define
35030 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
35040 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63  ure (xMutexAlloc
35050 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c  ,.** xMutexFree,
35060 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d   xMutexEnter, xM
35070 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c  utexTry, xMutexL
35080 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64  eave, xMutexHeld
35090 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f   and.** xMutexNo
350a0 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74  theld) implement
350b0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
350c0 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65  nterfaces (respe
350d0 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20  ctively):.**.** 
350e0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  <ul>.**   <li>  
350f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
35100 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  lloc()] </li>.**
35110 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
35120 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20  3_mutex_free()] 
35130 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
35140 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
35150 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  enter()] </li>.*
35160 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
35170 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20  e3_mutex_try()] 
35180 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
35190 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
351a0 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  leave()] </li>.*
351b0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
351c0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
351d0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
351e0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
351f0 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  _notheld()] </li
35200 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
35210 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
35220 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65  ence is that the
35230 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
35240 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e  XXX functions en
35250 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76  umerated.** abov
35260 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  e silently ignor
35270 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e  e any invocation
35280 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55  s that pass a NU
35290 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
352a0 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64  ad.** of a valid
352b0 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54   mutex handle. T
352c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
352d0 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64  ns of the method
352e0 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
352f0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
35300 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  re not required 
35310 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63  to handle this c
35320 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ase, the results
35330 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61  .** of passing a
35340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
35350 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64  stead of a valid
35360 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72   mutex handle ar
35370 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28  e undefined.** (
35380 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70  i.e. it is accep
35390 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65  table to provide
353a0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
353b0 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74  on that segfault
353c0 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61  s if.** it is pa
353d0 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ssed a NULL poin
353e0 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ter)..*/.typedef
353f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35400 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
35410 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
35420 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
35430 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
35440 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
35450 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
35460 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
35470 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
35480 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
35490 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
354a0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
354b0 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
354c0 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
354d0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
354e0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
354f0 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
35500 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
35510 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
35520 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
35530 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
35540 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
35550 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
35560 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
35570 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
35580 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
35590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
355a0 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
355b0 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 38   Routines {H1708
355c0 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 30  0} <S20130> <S30
355d0 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  800>.**.** The s
355e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
355f0 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
35600 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
35610 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
35620 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
35630 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
35640 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31   statements. {H1
35650 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 65  7081} The SQLite
35660 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75   core.** never u
35670 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
35680 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65  es except inside
35690 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64   an assert() and
356a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
356b0 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
356c0 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20  follow the lead 
356d0 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b 48  of the core.  {H
356e0 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 20  17082} The core 
356f0 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
35700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35710 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
35720 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
35730 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
35740 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
35750 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 7d   flag.  {A17087}
35760 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   External mutex 
35770 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
35780 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
35790 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
357a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
357b0 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
357c0 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
357d0 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
357e0 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
357f0 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 20   {H17083} These 
35800 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
35810 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
35820 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
35830 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
35840 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
35850 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
35860 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
35870 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58  thread..**.** {X
35880 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65  17084} The imple
35890 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
358a0 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
358b0 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
358c0 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
358d0 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
358e0 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69  y work. If the i
358f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
35900 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
35910 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
35920 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
35930 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
35940 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
35950 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61   stubs that alwa
35960 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75  ys.** return tru
35970 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
35980 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
35990 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61  ous assertion fa
359a0 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ilures..**.** {H
359b0 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72  17085} If the ar
359c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
359d0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
359e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
359f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
35a00 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
35a10 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69  rn 1.  {END} Thi
35a20 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
35a30 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
35a40 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
35a50 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
35a60 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
35a70 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
35a80 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
35a90 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
35aa0 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
35ab0 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
35ac0 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
35ad0 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
35ae0 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
35af0 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
35b00 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
35b10 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
35b20 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
35b30 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
35b40 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
35b50 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
35b60 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38  g to do.  {H1708
35b70 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  6} The sqlite3_m
35b80 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a  utex_notheld().*
35b90 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
35ba0 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
35bb0 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
35bc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
35bd0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
35be0 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
35bf0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
35c00 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
35c10 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
35c20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35c30 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b  F: Mutex Types {
35c40 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e  H17001} <H17000>
35c50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
35c60 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
35c70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
35c80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
35c90 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
35ca0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
35cb0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
35cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f  .**.** The set o
35cd0 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  f static mutexes
35ce0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
35cf0 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65   one SQLite rele
35d00 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  ase to the.** ne
35d10 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
35d20 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20  s that override 
35d30 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74  the built-in mut
35d40 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65  ex logic must be
35d50 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20  .** prepared to 
35d60 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69  accommodate addi
35d70 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
35d80 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  texes..*/.#defin
35d90 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
35da0 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
35db0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
35dc0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35dd0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
35de0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
35df0 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
35e00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
35e10 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
35e20 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
35e30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
35e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35e50 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
35e60 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f  M2      4  /* NO
35e70 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e  T USED */.#defin
35e80 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
35e90 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20  TATIC_OPEN      
35ea0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72  4  /* sqlite3Btr
35eb0 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66  eeOpen() */.#def
35ec0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
35ed0 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
35ee0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
35ef0 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
35f00 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
35f10 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
35f20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
35f30 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   list */.#define
35f40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
35f50 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37  ATIC_LRU2      7
35f60 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
35f70 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
35f80 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20  I3REF: Retrieve 
35f90 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20  the mutex for a 
35fa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fb0 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31  ion {H17002} <H1
35fc0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7000>.**.** This
35fd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35fe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65  ns a pointer the
35ff0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
36000 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a   object that .**
36010 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65   serializes acce
36020 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  ss to the [datab
36030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36040 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67  given in the arg
36050 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68  ument.** when th
36060 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
36070 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64  e] is Serialized
36080 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72  ..** If the [thr
36090 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
360a0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72  Single-thread or
360b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68   Multi-thread th
360c0 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  en this.** routi
360d0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
360e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
360f0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
36100 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71  ite3_db_mutex(sq
36110 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
36120 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65  CAPI3REF: Low-Le
36130 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44  vel Control Of D
36140 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48  atabase Files {H
36150 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11300} <S30800>.
36160 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54  **.** {H11301} T
36170 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
36180 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
36190 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
361a0 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
361b0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
361c0 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
361d0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
361e0 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
361f0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
36200 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
36210 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
36220 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
36230 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d  gument. {H11302}
36240 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   The.** name of 
36250 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
36260 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
36270 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
36280 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68  e by the.** <a h
36290 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
362a0 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
362b0 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68  > SQL command th
362c0 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a  at opened the.**
362d0 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33   database. {H113
362e0 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74  03} To control t
362f0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
36300 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e   file, use the n
36310 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72  ame "main".** or
36320 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
36330 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68   {H11304} The th
36340 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
36350 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
36360 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65  s routine.** are
36370 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79   passed directly
36380 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
36390 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
363a0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a   parameters of.*
363b0 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * the xFileContr
363c0 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31  ol method.  {H11
363d0 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20  305} The return 
363e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
363f0 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
36400 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
36410 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
36420 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
36430 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20  .** {H11306} If 
36440 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
36450 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64  eter (zDbName) d
36460 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68  oes not match th
36470 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a  e name of any.**
36480 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66   open database f
36490 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ile, then SQLITE
364a0 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e  _ERROR is return
364b0 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69  ed. {H11307} Thi
364c0 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
364d0 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
364e0 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
364f0 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
36500 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
36510 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
36520 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31  _errmsg()]. {A11
36530 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79  308} The underly
36540 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  ing xFileControl
36550 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a   method might.**
36560 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c   also return SQL
36570 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31  ITE_ERROR.  {A11
36580 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f  309} There is no
36590 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
365a0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
365b0 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
365c0 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
365d0 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
365e0 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
365f0 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
36600 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d  ol method. {END}
36610 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
36620 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
36630 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
36640 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
36650 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
36660 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
36670 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
36680 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
36690 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e  3REF: Testing In
366a0 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d  terface {H11400}
366b0 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
366c0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74  The sqlite3_test
366d0 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72  _control() inter
366e0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
366f0 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61  read out interna
36700 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51  l.** state of SQ
36710 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65  Lite and to inje
36720 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53  ct faults into S
36730 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e  QLite for testin
36740 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20  g.** purposes.  
36750 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
36760 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74  ter is an operat
36770 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65  ion code that de
36780 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20  termines.** the 
36790 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c  number, meaning,
367a0 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f   and operation o
367b0 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  f all subsequent
367c0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
367d0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
367e0 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65  e is not for use
367f0 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   by applications
36800 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c  .  It exists sol
36810 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66  ely.** for verif
36820 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74  ying the correct
36830 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
36840 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
36850 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  .  Depending.** 
36860 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74  on how the SQLit
36870 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d  e library is com
36880 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65  piled, this inte
36890 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20  rface might not 
368a0 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  exist..**.** The
368b0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
368c0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c  operation codes,
368d0 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c   their meanings,
368e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a   the parameters.
368f0 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e  ** they take, an
36900 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 61  d what they do a
36910 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74  re all subject t
36920 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
36930 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69   notice..** Unli
36940 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53  ke most of the S
36950 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 20  QLite API, this 
36960 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
36970 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a  guaranteed to.**
36980 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74   operate consist
36990 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72  ently from one r
369a0 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
369b0 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  xt..*/.int sqlit
369c0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
369d0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
369e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
369f0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
36a00 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73   Operation Codes
36a10 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30   {H11410} <H1140
36a20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
36a30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
36a40 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e   valid operation
36a50 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73   code parameters
36a60 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20   used.** as the 
36a70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
36a80 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  o [sqlite3_test_
36a90 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a  control()]..**.*
36aa0 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65  * These paramete
36ab0 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61  rs and their mea
36ac0 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63  nings are subjec
36ad0 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77  t to change.** w
36ae0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20  ithout notice.  
36af0 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65  These values are
36b00 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72   for testing pur
36b10 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41  poses only..** A
36b20 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
36b30 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f  ld not use any o
36b40 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
36b50 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  rs or the.** [sq
36b60 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
36b70 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
36b80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
36b90 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
36ba0 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20  _SAVE           
36bb0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
36bc0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
36bd0 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20  RNG_RESTORE     
36be0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
36bf0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
36c00 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20  L_PRNG_RESET    
36c10 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
36c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
36c30 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54  CTRL_BITVEC_TEST
36c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a                8.
36c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
36c60 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e  ESTCTRL_FAULT_IN
36c70 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20  STALL           
36c80 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
36c90 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47  E_TESTCTRL_BENIG
36ca0 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20  N_MALLOC_HOOKS  
36cb0 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
36cc0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45  LITE_TESTCTRL_PE
36cd0 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20  NDING_BYTE      
36ce0 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
36cf0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
36d00 5f 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20  _ASSERT         
36d10 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
36d20 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
36d30 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20  TRL_ALWAYS      
36d40 20 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 0a              13..
36d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d60 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53  SQLite Runtime S
36d70 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c  tatus {H17200} <
36d80 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60200>.** EXPER
36d90 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
36da0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
36db0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
36dc0 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20   runtime status 
36dd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
36de0 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d  bout the preform
36df0 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20  ance of SQLite, 
36e00 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74  and optionally t
36e10 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a  o reset various.
36e20 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  ** highwater mar
36e30 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  ks.  The first a
36e40 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
36e50 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a  teger code for.*
36e60 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70  * the specific p
36e70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73  arameter to meas
36e80 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64  ure.  Recognized
36e90 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a   integer codes.*
36ea0 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  * are of the for
36eb0 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53  m [SQLITE_STATUS
36ec0 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53  _MEMORY_USED | S
36ed0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e  QLITE_STATUS_...
36ee0 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  ]..** The curren
36ef0 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  t value of the p
36f00 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75  arameter is retu
36f10 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72  rned into *pCurr
36f20 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68  ent..** The high
36f30 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c  est recorded val
36f40 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ue is returned i
36f50 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20  n *pHighwater.  
36f60 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46  If the.** resetF
36f70 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65  lag is true, the
36f80 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65  n the highest re
36f90 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65  cord value is re
36fa0 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48  set after.** *pH
36fb0 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74  ighwater is writ
36fc0 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65  ten. Some parame
36fd0 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f  ters do not reco
36fe0 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a  rd the highest.*
36ff0 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
37000 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ose parameters.*
37010 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  * nothing is wri
37020 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68  tten into *pHigh
37030 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65  water and the re
37040 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72  setFlag is ignor
37050 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72  ed..** Other par
37060 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f  ameters record o
37070 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65  nly the highwate
37080 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74  r mark and not t
37090 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61  he current.** va
370a0 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20  lue.  For these 
370b0 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72  latter parameter
370c0 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  s nothing is wri
370d0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72  tten into *pCurr
370e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ent..**.** This 
370f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37100 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63  SQLITE_OK on suc
37110 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a  cess and a non-z
37120 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  ero.** [error co
37130 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
37140 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
37150 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ne is threadsafe
37160 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d   but is not atom
37170 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ic.  This routin
37180 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20  e can.** called 
37190 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65  while other thre
371a0 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20  ads are running 
371b0 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66  the same or diff
371c0 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20  erent SQLite.** 
371d0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
371e0 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20  ever the values 
371f0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75  returned in *pCu
37200 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48  rrent and.** *pH
37210 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74  ighwater reflect
37220 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53   the status of S
37230 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65  QLite at differe
37240 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d  nt points in tim
37250 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70  e.** and it is p
37260 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f  ossible that ano
37270 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68  ther thread migh
37280 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72  t change the par
37290 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74  ameter.** in bet
372a0 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77  ween the times w
372b0 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e  hen *pCurrent an
372c0 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72  d *pHighwater ar
372d0 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  e written..**.**
372e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
372f0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d  te3_db_status()]
37300 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
37310 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
37320 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f  te3_status(int o
37330 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74  p, int *pCurrent
37340 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65  , int *pHighwate
37350 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67  r, int resetFlag
37360 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
37370 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61  REF: Status Para
37380 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20  meters {H17250} 
37390 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <H17200>.** EXPE
373a0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
373b0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
373c0 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65  stants designate
373d0 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d   various run-tim
373e0 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74  e status paramet
373f0 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ers.** that can 
37400 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  be returned by [
37410 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
37420 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
37430 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54   <dt>SQLITE_STAT
37440 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f  US_MEMORY_USED</
37450 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37460 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37470 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20   current amount 
37480 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65  of memory checke
37490 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  d out.** using [
374a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
374b0 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74  ], either direct
374c0 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79  ly or indirectly
374d0 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65  .  The.** figure
374e0 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20   includes calls 
374f0 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33  made to [sqlite3
37500 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68  _malloc()] by th
37510 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
37520 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65   and internal me
37530 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68  mory usage by th
37540 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
37550 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72  .  Scratch memor
37560 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  y.** controlled 
37570 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
37580 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61  G_SCRATCH] and a
37590 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61  uxiliary page-ca
375a0 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f  che.** memory co
375b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c  ntrolled by [SQL
375c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
375d0 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63  ACHE] is not inc
375e0 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73  luded in.** this
375f0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
37600 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64   amount returned
37610 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74   is the sum of t
37620 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
37630 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74   sizes as report
37640 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20  ed by the xSize 
37650 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74  method in [sqlit
37660 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e  e3_mem_methods].
37670 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
37680 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41  SQLITE_STATUS_MA
37690 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  LLOC_SIZE</dt>.*
376a0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
376b0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
376c0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
376d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
376e0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
376f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37700 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
37710 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68  ealloc()] (or th
37720 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  eir.** internal 
37730 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f  equivalents).  O
37740 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
37750 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
37760 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
37770 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
37780 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
37790 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
377a0 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
377b0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
377c0 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
377d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
377e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
377f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
37800 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a  CACHE_USED</dt>.
37810 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
37820 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
37830 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
37840 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68  s used out of th
37850 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20  e.** [pagecache 
37860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
37870 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69  ] that was confi
37880 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20  gured using .** 
37890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
378a0 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a  AGECACHE].  The.
378b0 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ** value returne
378c0 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e  d is in pages, n
378d0 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  ot in bytes.</dd
378e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
378f0 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
37900 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  CHE_OVERFLOW</dt
37910 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
37920 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
37930 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37940 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68  tes of page cach
37950 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e.** allocation 
37960 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20  which could not 
37970 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79  be statisfied by
37980 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
37990 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a  FIG_PAGECACHE].*
379a0 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65  * buffer and whe
379b0 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65  re forced to ove
379c0 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65  rflow to [sqlite
379d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
379e0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61  e.** returned va
379f0 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  lue includes all
37a00 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ocations that ov
37a10 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65  erflowed because
37a20 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74   they.** where t
37a30 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77  oo large (they w
37a40 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  ere larger than 
37a50 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74  the "sz" paramet
37a60 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
37a70 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
37a80 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69  E]) and allocati
37a90 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f  ons that overflo
37aa0 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e  wed because.** n
37ab0 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74  o space was left
37ac0 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
37ad0 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  he.</dd>.**.** <
37ae0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
37af0 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c  _PAGECACHE_SIZE<
37b00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
37b10 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72   parameter recor
37b20 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d  ds the largest m
37b30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37b40 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64   request.** hand
37b50 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65  ed to [pagecache
37b60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
37b70 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61  r].  Only the va
37b80 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
37b90 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  the.** *pHighwat
37ba0 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  er parameter to 
37bb0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
37bc0 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73  )] is of interes
37bd0 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75  t.  .** The valu
37be0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  e written into t
37bf0 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72  he *pCurrent par
37c00 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69  ameter is undefi
37c10 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
37c20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
37c30 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f  S_SCRATCH_USED</
37c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37c50 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e  parameter return
37c60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37c70 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64  allocations used
37c80 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   out of the.** [
37c90 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61  scratch memory a
37ca0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
37cb0 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53  ured using.** [S
37cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
37cd0 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75  ATCH].  The valu
37ce0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e  e returned is in
37cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f   allocations, no
37d00 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20  t.** in bytes.  
37d10 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74  Since a single t
37d20 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68  hread may only h
37d30 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20  ave one scratch 
37d40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75  allocation.** ou
37d50 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d  tstanding at tim
37d60 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  e, this paramete
37d70 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74  r also reports t
37d80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  he number of thr
37d90 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63  eads.** using sc
37da0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20  ratch memory at 
37db0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f  the same time.</
37dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
37dd0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
37de0 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  TCH_OVERFLOW</dt
37df0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
37e00 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
37e10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37e20 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d  tes of scratch m
37e30 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37e40 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20  ion which could 
37e50 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65  not be statisfie
37e60 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
37e70 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
37e80 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77  .** buffer and w
37e90 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f  here forced to o
37ea0 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69  verflow to [sqli
37eb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
37ec0 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65  The values.** re
37ed0 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f  turned include o
37ee0 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65  verflows because
37ef0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61   the requested a
37f00 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f  llocation was to
37f10 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61  o.** larger (tha
37f20 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68  t is, because th
37f30 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f  e requested allo
37f40 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65  cation was large
37f50 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73  r than the.** "s
37f60 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  z" parameter to 
37f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
37f80 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63  CRATCH]) and bec
37f90 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20  ause no scratch 
37fa0 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20  buffer.** slots 
37fb0 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a  were available..
37fc0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
37fd0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
37fe0 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64  _SCRATCH_SIZE</d
37ff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
38000 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73  arameter records
38010 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d   the largest mem
38020 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
38030 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64  equest.** handed
38040 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d   to [scratch mem
38050 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20  ory allocator]. 
38060 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20   Only the value 
38070 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a  returned in the.
38080 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70  ** *pHighwater p
38090 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
380a0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69  ite3_status()] i
380b0 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20  s of interest.  
380c0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72  .** The value wr
380d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a  itten into the *
380e0 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74  pCurrent paramet
380f0 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  er is undefined.
38100 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
38110 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
38120 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a  RSER_STACK</dt>.
38130 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
38140 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68  meter records th
38150 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72  e deepest parser
38160 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f   stack.  It is o
38170 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75  nly.** meaningfu
38180 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  l if SQLite is c
38190 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59  ompiled with [YY
381a0 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50  TRACKMAXSTACKDEP
381b0 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  TH].</dd>.** </d
381c0 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61  l>.**.** New sta
381d0 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d  tus parameters m
381e0 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d  ay be added from
381f0 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a   time to time..*
38200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38210 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55  _STATUS_MEMORY_U
38220 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23  SED          0.#
38230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
38240 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55  ATUS_PAGECACHE_U
38250 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66  SED       1.#def
38260 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
38270 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52  S_PAGECACHE_OVER
38280 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65  FLOW   2.#define
38290 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53   SQLITE_STATUS_S
382a0 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20  CRATCH_USED     
382b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
382c0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
382d0 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20  TCH_OVERFLOW    
382e0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
382f0 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f  E_STATUS_MALLOC_
38300 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a  SIZE          5.
38310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
38320 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41  TATUS_PARSER_STA
38330 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65  CK         6.#de
38340 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
38350 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a  US_PAGECACHE_SIZ
38360 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e  E       7.#defin
38370 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
38380 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20  SCRATCH_SIZE    
38390 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41       8../*.** CA
383a0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
383b0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74   Connection Stat
383c0 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30  us {H17500} <S60
383d0 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
383e0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
383f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
38400 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75  d to retrieve ru
38410 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66  ntime status inf
38420 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f  ormation .** abo
38430 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74  ut a single [dat
38440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38450 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
38460 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
38470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38480 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62  tion object to b
38490 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  e interrogated. 
384a0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
384b0 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70  ment.** is the p
384c0 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65  arameter to inte
384d0 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e  rrogate.  Curren
384e0 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c  tly, the only al
384f0 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66  lowed value.** f
38500 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  or the second pa
38510 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49  rameter is [SQLI
38520 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b  TE_DBSTATUS_LOOK
38530 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20  ASIDE_USED]..** 
38540 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f  Additional optio
38550 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61  ns will likely a
38560 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20  ppear in future 
38570 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
38580 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75  te..**.** The cu
38590 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74  rrent value of t
385a0 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72  he requested par
385b0 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65  ameter is writte
385c0 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20  n into *pCur.** 
385d0 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20  and the highest 
385e0 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61  instantaneous va
385f0 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  lue is written i
38600 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66  nto *pHiwtr.  If
38610 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67  .** the resetFlg
38620 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
38630 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61  he highest insta
38640 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69  ntaneous value i
38650 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20  s.** reset back 
38660 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72  down to the curr
38670 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ent value..**.**
38680 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
38690 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e  te3_status()] an
386a0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  d [sqlite3_stmt_
386b0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51  status()]..*/.SQ
386c0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
386d0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  L int sqlite3_db
386e0 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a  _status(sqlite3*
386f0 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70  , int op, int *p
38700 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72  Cur, int *pHiwtr
38710 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b  , int resetFlg);
38720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38730 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74  : Status Paramet
38740 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65  ers for database
38750 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31   connections {H1
38760 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a  7520} <H17500>.*
38770 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
38780 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62  *.** Status verb
38790 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64  s for [sqlite3_d
387a0 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a  b_status()]..**.
387b0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
387c0 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c  QLITE_DBSTATUS_L
387d0 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64  OOKASIDE_USED</d
387e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
387f0 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
38800 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c   the number of l
38810 6f 6f 6b 61 73 69 6