/ Hex Artifact Content
Login

Artifact 0721c11055d2c60cc7579e56560916de82cf7620:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 33 37 20 32 30 30 39 2f 30  n,v 1.437 2009/0
05f0: 34 2f 30 32 20 31 38 3a 33 32 3a 32 37 20 64 72  4/02 18:32:27 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 23 64  R | (17<<8))..#d
4010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4020: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4030: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4040: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4050: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4060: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4070: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
4080: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
4090: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
40a0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
40b0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
40c0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
40d0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
40e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
40f0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4100: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
4110: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
4120: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
4130: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
4140: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
4150: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
4160: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
4170: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
4180: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4190: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
41a0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
41b0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
41c0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
41d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
41e0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
41f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
4200: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
4210: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4220: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
4230: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
4240: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4250: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
4260: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4270: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
4280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
4290: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
42a0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
42b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
42c0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
42d0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
42e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
42f0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4300: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
4310: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
4320: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4330: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
4340: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
4350: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
4360: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
4370: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
4380: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
4390: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
43a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
43b0: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
43c0: 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  08000.#define SQ
43d0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
43e0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
43f0: 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  10000../*.** CAP
4400: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
4410: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
4420: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
4430: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
4440: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
4450: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
4460: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
4480: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
4490: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
44a0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
44b0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
44c0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
44d0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
44e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
44f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
4500: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
4510: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
4520: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
4530: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
4540: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
4550: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
4560: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
4570: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
4580: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
4590: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
45a0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
45b0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
45c0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
45d0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
45e0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
45f0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
4600: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
4610: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
4620: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
4630: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
4640: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
4650: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
4660: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
4670: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
4680: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
4690: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
46a0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
46b0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
46c0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
46d0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
46e0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
46f0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
4700: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
4710: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
4720: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
4730: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
4740: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
4750: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
4760: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
4770: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
4780: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4790: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
47a0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
47b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
47c0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
47d0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
47e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
47f0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
4800: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
4810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4820: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
4830: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
4840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4850: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
4860: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
4870: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4880: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
4890: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
48a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
48b0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
48c0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
48d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
48e0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
48f0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
4900: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4910: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
4920: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
4930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
4940: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
4950: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
4960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4970: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
4980: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
4990: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
49a0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
49b0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
49c0: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
49d0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
49e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
49f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
4a00: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
4a10: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
4a20: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
4a30: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
4a40: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
4a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4a80: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
4a90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
4aa0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
4ab0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
4ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
4ad0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
4ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4af0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4b10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4b20: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4b30: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4b40: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
4b50: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
4b60: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
4b70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
4b80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
4b90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
4ba0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4bb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
4bc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
4bd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4be0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4bf0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
4c00: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
4c10: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4c20: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
4c30: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
4c40: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
4c50: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
4c60: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
4c70: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
4c80: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
4c90: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
4ca0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
4cb0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
4cc0: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
4cd0: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
4ce0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
4cf0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
4d00: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
4d10: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
4d20: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
4d30: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
4d40: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4d50: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
4d60: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
4d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d80: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
4d90: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
4da0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
4db0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
4dc0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
4dd0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4de0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
4df0: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
4e00: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
4e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
4e20: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
4e30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
4e40: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
4e50: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
4e60: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
4e70: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
4e80: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
4e90: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
4ea0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
4eb0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
4ec0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
4ed0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
4ee0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
4ef0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
4f00: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
4f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
4f20: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
4f30: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
4f40: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
4f50: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
4f60: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
4f70: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
4f80: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
4f90: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
4fa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
4fb0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
4fc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4fd0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
4fe0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
4ff0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5000: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5010: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5020: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5030: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
5040: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
5050: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
5060: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
5070: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
5080: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
5090: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
50a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
50b0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
50c0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
50d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
50e0: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
50f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
5100: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
5110: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
5120: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
5130: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
5140: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
5150: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
5160: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
5170: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
5180: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
5190: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
51a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
51b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
51c0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
51d0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
51e0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
51f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
5200: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
5210: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
5220: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
5230: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
5240: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
5250: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
5260: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
5270: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
5280: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
5290: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
52a0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
52b0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
52c0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
52d0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
52e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
52f0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
5300: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5310: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
5320: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5330: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
5340: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
5350: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5360: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5370: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5380: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5390: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
53a0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
53c0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
53d0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
53e0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
53f0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
5400: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
5410: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5420: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
5430: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
5440: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
5450: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
5460: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
5470: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
5480: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
5490: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
54a0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
54b0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
54c0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
54d0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
54e0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
54f0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
5500: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
5510: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
5520: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
5530: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
5540: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
5550: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
5560: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
5570: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
5580: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
5590: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
55a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
55b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
55c0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
55d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
55e0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
55f0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
5600: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
5610: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
5620: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
5630: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
5640: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
5650: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
5660: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
5670: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
5680: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
5690: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
56a0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
56b0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
56c0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
56d0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
56e0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
56f0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
5700: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
5710: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
5720: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
5730: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
5740: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
5750: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
5760: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
5770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
5780: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
5790: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
57a0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
57b0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
57c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
57d0: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
57e0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
57f0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
5800: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
5810: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
5820: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
5830: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
5840: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
5850: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
5860: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
5870: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
5880: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
5890: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
58a0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
58b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
58c0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
58d0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
58e0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
58f0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
5900: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
5910: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
5920: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
5930: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
5940: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
5950: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
5960: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
5970: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
5980: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
5990: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
59a0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
59b0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
59c0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
59d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
59e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
59f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
5a00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
5a20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
5a40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5a80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
5aa0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5ac0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5b00: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
5b10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
5b20: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
5b30: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
5b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5b60: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
5b70: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
5b80: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ba0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5bb0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
5bc0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
5bd0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
5be0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
5bf0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
5c00: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
5c10: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5c20: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5c30: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c50: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
5c60: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
5c70: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
5c80: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
5c90: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5ca0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5cb0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5cc0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5cd0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5ce0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5cf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5d00: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5d10: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5d20: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5d30: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5d40: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5d50: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5d60: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5d70: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
5d80: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
5d90: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5da0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
5db0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
5dc0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
5dd0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
5de0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
5df0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
5e00: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
5e10: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
5e20: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
5e30: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
5e40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5e50: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
5e60: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
5e70: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
5e80: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
5e90: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5ea0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
5eb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
5ec0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
5ed0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
5ee0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
5ef0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
5f00: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
5f10: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
5f20: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
5f30: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
5f40: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
5f50: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
5f60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5f70: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
5f80: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
5f90: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
5fa0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
5fb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
5fc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
5fd0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
5fe0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
5ff0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
6000: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
6010: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6020: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
6030: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
6040: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
6050: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
6060: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
6070: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6080: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
6090: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
60a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
60b0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
60c0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
60d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
60e0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
60f0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
6100: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
6110: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6120: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6130: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6140: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6150: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6160: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6170: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6180: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6190: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
61a0: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
61b0: 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20  pcodes {H11310} 
61c0: 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
61d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
61e0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
61f0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
6200: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
6210: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
6220: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6230: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
6240: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
6250: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
6260: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
6270: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
6280: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
6290: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
62a0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
62b0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
62c0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
62d0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
62e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
62f0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
6300: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
6310: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
6320: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6330: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
6340: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
6350: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6360: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
6370: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6380: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
6390: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
63a0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
63b0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
63c0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
63d0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
63e0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
63f0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
6400: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
6410: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6440: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
6460: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
6470: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6480: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
6490: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
64a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
64b0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
64c0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
64d0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
64e0: 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33   {H17110} <S2013
64f0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  0>.**.** The mut
6500: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
6510: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
6520: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6530: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
6540: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
6550: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
6560: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
6570: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
6580: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
6590: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
65a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
65b0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
65c0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
65d0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
65e0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
65f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
6600: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
6610: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
6620: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
6630: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6640: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
6650: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
6660: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6670: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20  nterface Object 
6680: 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30  {H11140} <S20100
6690: 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  >.**.** An insta
66a0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
66b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
66c0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
66d0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
66e0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
66f0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
6700: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
6710: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
6720: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
6730: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
6740: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
6750: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
6760: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
6770: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
6780: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
6790: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
67a0: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
67b0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
67c0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
67d0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
67e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
67f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
6800: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
6810: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
6820: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
6830: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
6840: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
6850: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
6860: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
6870: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
6880: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
6890: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
68a0: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
68b0: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
68c0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
68d0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
68e0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
68f0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
6900: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
6910: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
6920: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
6930: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
6940: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
6950: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
6960: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
6970: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
6980: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
6990: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
69a0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
69b0: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
69c0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
69d0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
69e0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
69f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
6a00: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
6a10: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
6a20: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
6a30: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
6a40: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
6a50: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
6a60: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
6a70: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
6a80: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
6a90: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
6aa0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
6ab0: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
6ac0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
6ad0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
6ae0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
6af0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
6b00: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
6b10: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
6b20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
6b30: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
6b40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
6b50: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
6b60: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
6b70: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
6b80: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
6b90: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
6ba0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
6bb0: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
6bc0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
6bd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
6be0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
6bf0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
6c00: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
6c10: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
6c20: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
6c30: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
6c40: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
6c50: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
6c60: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
6c70: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
6c80: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
6c90: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
6ca0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
6cb0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
6cc0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
6cd0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
6ce0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
6cf0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
6d00: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
6d10: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
6d20: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
6d30: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
6d40: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
6d50: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
6d60: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
6d70: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
6d80: 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a  ous sentense,.**
6d90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6da0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
6db0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
6dc0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
6dd0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
6de0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
6df0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
6e00: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
6e10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6e20: 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69  meter is xOpen i
6e30: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
6e40: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
6e50: 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f  ust invite its o
6e60: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
6e70: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
6e80: 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a   Whenever the .*
6e90: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
6ea0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
6eb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
6ec0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
6ed0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
6ee0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
6ef0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
6f00: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
6f10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6f20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
6f30: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
6f40: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
6f50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6f60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
6f70: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
6f80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
6f90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
6fa0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
6fb0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
6fc0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
6fd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
6fe0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
6ff0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
7000: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
7010: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
7020: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
7030: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
7040: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
7050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7060: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
7070: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
7080: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
7090: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
70a0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
70b0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
70c0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
70d0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
70e0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
70f0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
7100: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7110: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7120: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
7130: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7140: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
7150: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7160: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
7170: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7180: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
7190: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
71a0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
71b0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
71c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
71d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
71e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
71f0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
7200: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7210: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
7220: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
7230: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
7240: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
7250: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
7260: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
7270: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
7280: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
7290: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
72a0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
72b0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
72c0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
72d0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
72e0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
72f0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
7300: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
7310: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
7320: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
7330: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
7340: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
7350: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
7360: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
7370: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7380: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
7390: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
73a0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
73b0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
73c0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
73d0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
73e0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
73f0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
7400: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
7410: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
7420: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
7430: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
7440: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
7450: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
7460: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
7470: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7480: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7490: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
74a0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
74b0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
74c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74d0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
74e0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
74f0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
7500: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
7510: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
7520: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7540: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
7550: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
7560: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
7570: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
7580: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
7590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
75a0: 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  IVE] flag means 
75b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
75c0: 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72  be opened.** for
75d0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
75e0: 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73  s.  This flag is
75f0: 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c   set for all fil
7600: 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72  es except.** for
7610: 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
7620: 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  se file..**.** A
7630: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
7640: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
7650: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
7660: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
7670: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
7680: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
7690: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
76a0: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
76b0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
76c0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
76d0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
76e0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
76f0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
7700: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
7710: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66   in..**.** The f
7720: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7730: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7740: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7750: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
7760: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
7770: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
7780: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
7790: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
77a0: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
77b0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
77c0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
77d0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
77e0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
77f0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
7800: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
7810: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
7820: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
7830: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
7840: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
7850: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
7860: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
7870: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
7880: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
7890: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
78a0: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
78b0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
78c0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
78d0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
78e0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
78f0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
7900: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
7910: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
7920: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
7930: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
7940: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
7950: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
7960: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
7970: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
7980: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
7990: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
79a0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
79b0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
79c0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
79d0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
79e0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
79f0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
7a00: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
7a10: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
7a20: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
7a30: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
7a40: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
7a50: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
7a60: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
7a70: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
7a80: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
7a90: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
7aa0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
7ab0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
7ac0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
7ad0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
7ae0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
7af0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
7b00: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
7b10: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
7b20: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
7b30: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
7b40: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
7b50: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
7b60: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
7b70: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
7b80: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
7b90: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
7ba0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
7bb0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
7bc0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
7bd0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7be0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
7bf0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
7c00: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
7c10: 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65  me..**.*/.typede
7c20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7c30: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
7c40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7c50: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
7c60: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
7c70: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
7c80: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
7c90: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
7ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
7cb0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
7cc0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
7cd0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
7ce0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
7cf0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
7d00: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
7d10: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
7d20: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
7d30: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
7d40: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
7d50: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
7d60: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
7d70: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7d80: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
7d90: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
7da0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
7db0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
7dc0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
7dd0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
7de0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7df0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
7e00: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
7e10: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
7e20: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
7e30: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7e40: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
7e50: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7e60: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
7e70: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
7e80: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
7e90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7ea0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
7eb0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
7ec0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
7ed0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
7ee0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ef0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
7f00: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
7f10: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
7f20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
7f30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
7f40: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
7f50: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
7f60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7f70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
7f80: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
7f90: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
7fa0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
7fb0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
7fc0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
7fd0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
7fe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
7ff0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
8000: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
8010: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
8020: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8030: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
8040: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8050: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
8060: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
8070: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
8080: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
8090: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
80a0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
80b0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
80c0: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  /* New fields
80d0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
80e0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
80f0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
8100: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
8110: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
8120: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
8130: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ns. */.};../*.**
8140: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
8150: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
8160: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31   VFS method {H11
8170: 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a  190} <H11140>.**
8180: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8190: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
81a0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
81b0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
81c0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
81d0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
81e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
81f0: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
8200: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
8210: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
8220: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
8230: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
8240: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
8250: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
8260: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
8270: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
8280: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
8290: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
82a0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
82b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
82c0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
82d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
82e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
82f0: 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  le is both reada
8300: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
8310: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8320: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
8330: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8340: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
8350: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
8360: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
8370: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8380: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
8390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
83b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83c0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
83d0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
83e0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
83f0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
8400: 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30   {H10130} <S2000
8410: 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
8420: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
8430: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
8440: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
8450: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
8460: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
8470: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
8480: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
8490: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
84a0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
84b0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
84c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
84d0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
84e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
84f0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
8500: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
8510: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
8520: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
8530: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
8540: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
8550: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
8560: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
8570: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
8580: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8590: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
85a0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
85b0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
85c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
85d0: 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65  ).  Only an effe
85e0: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
85f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8600: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
8610: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
8620: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
8630: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
8640: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d  no-ops..**.** Am
8650: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
8660: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
8670: 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76  lize() shall inv
8680: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
8690: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
86a0: 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68  arly, sqlite3_sh
86b0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c  utdown().** shal
86c0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
86d0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
86e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
86f0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
8700: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
8710: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
8720: 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65  ..** If for some
8730: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
8740: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8750: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
8760: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
8770: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
8780: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
8790: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
87a0: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
87b0: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
87c0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
87d0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
87e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
87f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
8800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
8810: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
8820: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
8830: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
8840: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
8850: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
8860: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
8870: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
8880: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
8890: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
88a0: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
88b0: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
88c0: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
88d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
88e0: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
88f0: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
8900: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
8910: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
8920: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
8930: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
8940: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
8950: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
8960: 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65  already.  Howeve
8970: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
8980: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
8990: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
89a0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
89b0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
89c0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
89d0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
89e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
89f0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
8a00: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
8a10: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
8a20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8a30: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
8a40: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
8a50: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
8a60: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
8a70: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
8a80: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
8a90: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
8aa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
8ab0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
8ac0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
8ad0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
8ae0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
8af0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
8b00: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
8b10: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
8b20: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
8b30: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
8b40: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
8b50: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
8b60: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
8b70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
8b80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
8b90: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
8ba0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
8bb0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
8bc0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
8bd0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8be0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
8bf0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
8c00: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
8c10: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
8c20: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
8c30: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
8c40: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
8c50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
8c60: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
8c70: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
8c80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
8c90: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
8ca0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
8cb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
8cc0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
8cd0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
8ce0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
8cf0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
8d00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
8d10: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
8d20: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
8d30: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
8d40: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
8d50: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
8d60: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
8d70: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
8d80: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
8d90: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
8da0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
8db0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
8dc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
8dd0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
8de0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
8df0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
8e00: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
8e10: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
8e20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
8e30: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
8e40: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
8e50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
8e60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
8e70: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
8e80: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
8e90: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
8ea0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
8eb0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
8ec0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8ed0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
8ee0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
8ef0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
8f00: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
8f10: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
8f20: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
8f30: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
8f40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
8f50: 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f  unix, windows, o
8f60: 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r os/2..** When 
8f70: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
8f80: 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67  platforms (using
8f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
8fa0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
8fb0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
8fc0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8fd0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
8fe0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
8ff0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9000: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9010: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9020: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9030: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9060: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9070: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9080: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9090: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
90a0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
90b0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
90c0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
90d0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
90e0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
90f0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9100: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9110: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9120: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9130: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9140: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9150: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9160: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9170: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9180: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9190: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
91a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
91b0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
91c0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
91d0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
91e0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
91f0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9200: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9210: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9220: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9230: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9240: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9250: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9260: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9270: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9280: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9290: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
92a0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
92b0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
92c0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
92d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
92e0: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
92f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9300: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9310: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9320: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9330: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9340: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9350: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
9360: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
9370: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
9380: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
9390: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
93a0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
93b0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
93c0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
93d0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
93e0: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
93f0: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
9400: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
9410: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9420: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
9430: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
9440: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
9450: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
9460: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
9470: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
9480: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
9490: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
94a0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
94b0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
94c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
94d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
94e0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
94f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9500: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
9510: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
9520: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
9530: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9540: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
9550: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
9560: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
9570: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
9580: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
9590: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
95a0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
95b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
95c0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
95d0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
95e0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
95f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
9600: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
9610: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9620: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
9630: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
9640: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9650: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
9660: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
9670: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
9680: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
9690: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
96a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
96b0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
96c0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
96d0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
96e0: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
96f0: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
9700: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
9710: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
9720: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
9730: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
9740: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
9750: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
9760: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
9770: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
9780: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
9790: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
97a0: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
97b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
97c0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
97d0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
97e0: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
97f0: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
9800: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
9810: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
9820: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
9830: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9840: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
9850: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
9860: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
9870: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
9880: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
9890: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
98a0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
98b0: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
98c0: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
98d0: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
98e0: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
98f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
9900: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
9910: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
9920: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
9930: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
9940: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
9950: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
9960: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
9970: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9980: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
9990: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
99a0: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
99b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
99c0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
99d0: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
99e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
99f0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
9a00: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
9a10: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
9a20: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
9a30: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
9a40: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
9a50: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
9a60: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
9a70: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
9a80: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
9a90: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
9aa0: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
9ab0: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
9ac0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
9ad0: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
9ae0: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
9af0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
9b00: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
9b10: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
9b20: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
9b30: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
9b40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
9b50: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
9b60: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
9b70: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
9b80: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
9b90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
9ba0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
9bb0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
9bc0: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
9bd0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
9be0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
9bf0: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
9c00: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
9c10: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
9c20: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
9c30: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
9c40: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
9c50: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
9c60: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
9c70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9c80: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9c90: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
9ca0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
9cb0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
9cc0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
9cd0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
9ce0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
9cf0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
9d00: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
9d10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
9d20: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
9d30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
9d40: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
9d50: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
9d60: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
9d70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
9d80: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
9d90: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
9da0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
9db0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
9dc0: 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c  tion, an.** appl
9dd0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
9de0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
9df0: 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ve memory alloca
9e00: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a  tion subsystem.*
9e10: 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  * for SQLite to 
9e20: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
9e30: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
9e40: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
9e50: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
9e60: 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69  comes with a bui
9e70: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
9e80: 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a  ocator that is.*
9e90: 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  * perfectly adeq
9ea0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
9eb0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
9ec0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
9ed0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
9ee0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
9ef0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
9f00: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
9f10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
9f20: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
9f30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
9f40: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
9f50: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
9f60: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
9f70: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
9f80: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
9f90: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
9fa0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
9fb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
9fc0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
9fd0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
9fe0: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
9ff0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
a000: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
a010: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
a020: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
a030: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
a040: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
a050: 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c  Free, and xReall
a060: 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  oc methods must 
a070: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
a080: 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28   malloc(), free(
a090: 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29  ), and realloc()
a0a0: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
a0b0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
a0c0: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  rary..**.** xSiz
a0d0: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
a0e0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
a0f0: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
a100: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
a110: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
a120: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
a130: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
a140: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
a150: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
a160: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
a170: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
a180: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
a190: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
a1a0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
a1b0: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
a1c0: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
a1d0: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
a1e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a1f0: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
a200: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
a210: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
a220: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
a230: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
a240: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
a250: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
a260: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
a270: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
a280: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
a290: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
a2a0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
a2b0: 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  of 2..**.** The 
a2c0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
a2d0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
a2e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
a2f0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
a300: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
a310: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
a320: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
a330: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
a340: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
a350: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
a360: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
a370: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
a380: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
a390: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
a3a0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
a3b0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
a3c0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
a3d0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
a3e0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
a3f0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
a400: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
a410: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
a420: 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  wn..*/.typedef s
a430: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
a440: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
a450: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
a460: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
a470: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
a480: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
a490: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
a4a0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
a4b0: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
a4c0: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
a4d0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
a4e0: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
a4f0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
a500: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
a510: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
a520: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
a530: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
a540: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
a550: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
a560: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
a570: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
a580: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
a590: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
a5a0: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
a5b0: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
a5c0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
a5d0: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
a5e0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
a5f0: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
a600: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
a610: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
a620: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
a630: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
a640: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
a650: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
a660: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
a670: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
a680: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
a690: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
a6a0: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
a6b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a6c0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
a6d0: 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c  tions {H10160} <
a6e0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
a6f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a700: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
a710: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
a720: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
a730: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
a740: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
a750: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
a760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a770: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a780: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
a790: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
a7a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
a7b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
a7c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
a7d0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
a7e0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
a7f0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
a800: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
a810: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
a820: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
a830: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
a840: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
a850: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
a860: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
a870: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
a880: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
a890: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
a8a0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
a8b0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
a8c0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
a8d0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
a8e0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
a8f0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
a900: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
a910: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
a920: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
a930: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
a940: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
a950: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
a960: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
a970: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
a980: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
a990: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
a9a0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
a9b0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
a9c0: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
a9d0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
a9e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
a9f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
aa00: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
aa10: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
aa20: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
aa30: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
aa40: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
aa50: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
aa60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
aa70: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
aa80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
aa90: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
aaa0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
aab0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
aac0: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
aad0: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
aae0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
aaf0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ab00: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
ab10: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
ab20: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
ab30: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
ab40: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
ab50: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
ab60: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
ab70: 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
ab80: 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
ab90: 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
aba0: 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
abb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
abc0: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
abd0: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
abe0: 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75  ng mode].** docu
abf0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
ac00: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
ac10: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ac20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ac30: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
ac40: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
ac50: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
ac60: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
ac70: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e    This option en
ac80: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
ac90: 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
aca0: 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
acb0: 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
acc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
acd0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
ace0: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
acf0: 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
ad00: 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
ad10: 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
ad20: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ad30: 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
ad40: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
ad50: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
ad60: 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
ad70: 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
ad80: 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
ad90: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
ada0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
adb0: 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
adc0: 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
add0: 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
ade0: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
adf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ae00: 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
ae10: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ae20: 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
ae30: 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
ae40: 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65  same time..** Se
ae50: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
ae60: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61   mode] documenta
ae70: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
ae80: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
ae90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
aea0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
aeb0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
aec0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
aed0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
aee0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
aef0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
af00: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
af10: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
af20: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
af30: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
af40: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
af50: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
af60: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
af70: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
af80: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
af90: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
afa0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
afb0: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
afc0: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
afd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
afe0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
aff0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b000: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b010: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b020: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b030: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b040: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b050: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b060: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b070: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
b080: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
b090: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
b0a0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
b0b0: 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
b0c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
b0d0: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
b0e0: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
b0f0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
b100: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
b110: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
b120: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
b130: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
b140: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
b150: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
b160: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
b170: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
b180: 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a   example.</dd>.*
b190: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b1a0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
b1b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b1c0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
b1d0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
b1e0: 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
b1f0: 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
b200: 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
b210: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
b220: 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
b230: 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
b240: 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
b250: 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73  istics. When dis
b260: 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
b270: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
b280: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a  rfaces become .*
b290: 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  * non-operationa
b2a0: 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
b2b0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b2c0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
b2d0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b2e0: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
b2f0: 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
b300: 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
b310: 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20  ap_limit()].**  
b320: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
b330: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
b340: 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ul>.** </dd>.**.
b350: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b360: 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
b370: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b380: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
b390: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
b3a0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
b3b0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
b3c0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
b3d0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
b3e0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
b3f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
b400: 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69  emory, the.** si
b410: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
b420: 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ch buffer (sz), 
b430: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
b440: 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20  f buffers (N).  
b450: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
b460: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
b470: 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65  tiple of 16. The
b480: 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68   sz parameter sh
b490: 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79  ould be a few by
b4a0: 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68  tes.** larger th
b4b0: 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63  an the actual sc
b4c0: 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75  ratch space requ
b4d0: 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61  ired due interna
b4e0: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54  l overhead..** T
b4f0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
b500: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
b510: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
b520: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
b530: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
b540: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
b550: 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
b560: 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
b570: 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20   buffer at once 
b580: 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a  per thread, so.*
b590: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
b5a0: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
b5b0: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
b5c0: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68   of threads.  Th
b5d0: 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65  e sz.** paramete
b5e0: 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69  r should be 6 ti
b5f0: 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  mes the size of 
b600: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
b610: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
b620: 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65  ** Scratch buffe
b630: 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70  rs are used as p
b640: 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65  art of the btree
b650: 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69   balance operati
b660: 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62  on.  If.** The b
b670: 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65  tree balancer ne
b680: 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d  eds additional m
b690: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
b6a0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
b6b0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66  .** scratch buff
b6c0: 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72  ers or if no scr
b6d0: 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63  atch buffer spac
b6e0: 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  e is specified, 
b6f0: 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67  then SQLite.** g
b700: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
b710: 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74  malloc()] to obt
b720: 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  ain the memory i
b730: 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a  t needs.</dd>.**
b740: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
b750: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
b760: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b770: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b780: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b790: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b7a0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b7b0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
b7c0: 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
b7d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
b7e0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
b7f0: 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
b800: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
b810: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
b820: 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
b830: 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
b840: 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
b850: 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
b860: 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
b870: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
b880: 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
b890: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
b8a0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
b8b0: 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
b8c0: 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  to the.** memory
b8d0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
b8e0: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
b8f0: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
b900: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
b910: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
b920: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
b930: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
b940: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
b950: 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  8.  The first.**
b960: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
b970: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
b980: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
b990: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
b9a0: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
b9b0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
b9c0: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
b9d0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
b9e0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
b9f0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
ba00: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
ba10: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
ba20: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
ba30: 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61  e.  If additiona
ba40: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
ba50: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
ba60: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
ba70: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
ba80: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
ba90: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
baa0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
bab0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
bac0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
bad0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  ace..** The impl
bae0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
baf0: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   use one or more
bb00: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72   of the N buffer
bb10: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65  s to hold .** me
bb20: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
bb30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64  information. </d
bb40: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
bb50: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
bb60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bb70: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
bb80: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
bb90: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
bba0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
bbb0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
bbc0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
bbd0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
bbe0: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
bbf0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
bc00: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
bc10: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
bc20: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
bc30: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
bc40: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
bc50: 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  nts: A pointer t
bc60: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
bc70: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
bc80: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
bc90: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
bca0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
bcb0: 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a  ation size.  If.
bcc0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  ** the first poi
bcd0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
bce0: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
bcf0: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
bd00: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
bd10: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
bd20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
bd30: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
bd40: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
bd50: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
bd60: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
bd70: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
bd80: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
bd90: 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f    If the.** memo
bda0: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
bdb0: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
bdc0: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
bdd0: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
bde0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
bdf0: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
be00: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
be10: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
be20: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
be30: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
be40: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
be50: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
be60: 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a  ion needs.</dd>.
be70: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
be80: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
be90: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
bea0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
beb0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
bec0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
bed0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
bee0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
bef0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
bf00: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bf10: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
bf20: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
bf30: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
bf40: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
bf50: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
bf60: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
bf70: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
bf80: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
bf90: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
bfa0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
bfb0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bfc0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bfd0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bfe0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bff0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c000: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c010: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c020: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c030: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
c040: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
c050: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
c060: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
c070: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
c080: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
c090: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
c0a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c0b0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
c0c0: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
c0d0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
c0e0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
c0f0: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
c100: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
c110: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
c120: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
c130: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  g, for example.<
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
c160: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
c170: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c180: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
c190: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
c1a0: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
c1b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f   memory allcatio
c1c0: 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69  n lookaside opti
c1d0: 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66  mization.  The f
c1e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
c1f0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
c200: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
c210: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
c220: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
c230: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
c240: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
c250: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
c260: 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  onnection.</dd>.
c270: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c280: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
c290: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c2a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
c2b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
c2c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
c2d0: 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
c2e0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
c2f0: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  ds] object.  Thi
c300: 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
c310: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c320: 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
c330: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
c340: 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69  mentation.  SQLi
c350: 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
c360: 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
c370: 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
c380: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
c390: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
c3a0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c3b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c3c0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
c3d0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c3e0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c3f0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c400: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c410: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
c420: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
c430: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
c440: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
c450: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
c460: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
c470: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
c480: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
c490: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
c4a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
c4b0: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
c4c0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
c4d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
c4e0: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
c4f0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
c500: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
c510: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
c520: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
c530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c540: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
c550: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
c560: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
c570: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c580: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
c590: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
c5a0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c5c0: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
c5d0: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
c5e0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
c5f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c600: 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
c610: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
c620: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
c630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c640: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
c650: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
c660: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
c670: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
c680: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
c690: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
c6a0: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c6c0: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
c6d0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
c6e0: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c700: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
c710: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
c720: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
c730: 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
c740: 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
c750: 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
c760: 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
c770: 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
c780: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
c790: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
c7a0: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
c7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c7c0: 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
c7d0: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
c7e0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
c7f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c800: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
c810: 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
c820: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
c830: 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  s* */../*.** CAP
c840: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
c850: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
c860: 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0170} <S20000>.*
c870: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c880: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
c890: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
c8a0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
c8b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c8c0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
c8d0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
c8e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
c8f0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
c900: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
c910: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
c920: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
c930: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
c940: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
c950: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
c960: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
c970: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c980: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
c990: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
c9a0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
c9b0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
c9c0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
c9d0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c9e0: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
c9f0: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
ca00: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
ca10: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
ca20: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
ca30: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
ca40: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
ca50: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
ca60: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
ca70: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
ca80: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
ca90: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
caa0: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
cab0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cac0: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
cad0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
cae0: 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
caf0: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
cb00: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
cb10: 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
cb20: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
cb30: 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
cb40: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
cb50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cb60: 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
cb70: 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
cb80: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cb90: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
cba0: 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
cbb0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
cbc0: 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
cbd0: 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
cbe0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72  memory.  The fir
cbf0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  st.** argument m
cc00: 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
cc10: 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
cc20: 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
cc30: 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62  e lookaside.** b
cc40: 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
cc50: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
cc60: 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f  oc()].  The seco
cc70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
cc80: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
cc90: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
cca0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
ccb0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
ccc0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
ccd0: 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
cce0: 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
ccf0: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
cd00: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
cd10: 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
cd20: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
cd30: 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
cd40: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
cd50: 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e   arguments.</dd>
cd60: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
cd70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
cd80: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
cd90: 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
cda0: 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
cdb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cdc0: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
cdd0: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
cde0: 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30  lt Codes {H12200
cdf0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
ce00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
ce10: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
ce20: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
ce30: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
ce40: 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
ce50: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
ce60: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
ce70: 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  e. The extended 
ce80: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
ce90: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
cea0: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
ceb0: 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
cec0: 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69  lity considerati
ced0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ons..**.** Requi
cee0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
cef0: 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f  201] [H12202].*/
cf00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
cf10: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
cf20: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
cf30: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
cf40: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
cf50: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32  nsert Rowid {H12
cf60: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
cf70: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
cf80: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
cf90: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
cfa0: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
cfb0: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
cfc0: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
cfd0: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f  "rowid"]. The ro
cfe0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
cff0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
d000: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
d010: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
d020: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
d030: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
d040: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
d050: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
d060: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
d070: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
d080: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
d090: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
d0a0: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
d0b0: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
d0c0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
d0d0: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
d0e0: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
d0f0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
d100: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
d110: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
d120: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
d130: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
d140: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
d150: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
d160: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
d170: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
d180: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
d190: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
d1a0: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
d1b0: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
d1c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d1d0: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
d1e0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
d1f0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
d200: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
d210: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b  gger, then the [
d220: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
d230: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73  serted.** row is
d240: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
d250: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
d260: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
d270: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
d280: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
d290: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c  gger terminates,
d2a0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d2b0: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
d2c0: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74  ine.** reverts t
d2d0: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65  o the last value
d2e0: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
d2f0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72   the trigger fir
d300: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e  ed..**.** An [IN
d310: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
d320: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
d330: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
d340: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
d350: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
d360: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
d370: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
d380: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
d390: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
d3a0: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
d3b0: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
d3c0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
d3d0: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
d3e0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
d3f0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
d400: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
d410: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
d420: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
d430: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
d440: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
d450: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
d460: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
d470: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
d480: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
d490: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
d4a0: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
d4b0: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
d4c0: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
d4d0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
d4e0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
d4f0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
d500: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
d510: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
d520: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
d530: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
d540: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
d550: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
d560: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
d570: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
d580: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
d590: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
d5a0: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
d5b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
d5c0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
d5d0: 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48  :.** [H12221] [H
d5e0: 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12223].**.** If 
d5f0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
d600: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
d610: 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
d620: 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
d630: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
d640: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
d650: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d660: 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
d670: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
d680: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
d690: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
d6a0: 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
d6b0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
d6c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
d6d0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
d6e0: 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
d6f0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
d700: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
d710: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
d720: 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
d730: 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
d740: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
d750: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
d760: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
d770: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d780: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
d790: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
d7a0: 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
d7b0: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
d7c0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
d7d0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
d7e0: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
d7f0: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
d800: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
d810: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
d820: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d830: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
d840: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
d850: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
d860: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
d870: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
d880: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
d890: 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
d8a0: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
d8b0: 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
d8c0: 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
d8d0: 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
d8e0: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
d8f0: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
d900: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
d910: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
d920: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
d930: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
d940: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d950: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
d960: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
d970: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d980: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
d990: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
d9a0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
d9b0: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
d9c0: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
d9d0: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
d9e0: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
d9f0: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
da00: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
da10: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
da20: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
da30: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
da40: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
da50: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
da60: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
da70: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
da80: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
da90: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
daa0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
dab0: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
dac0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
dad0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
dae0: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
daf0: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
db00: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
db10: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
db20: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
db30: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
db40: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
db50: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
db60: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
db70: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
db80: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
db90: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
dba0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
dbb0: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
dbc0: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
dbd0: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
dbe0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
dbf0: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
dc00: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
dc10: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
dc20: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
dc30: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
dc40: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
dc50: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
dc60: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
dc70: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
dc80: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
dc90: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
dca0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
dcb0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
dcc0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
dcd0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
dce0: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
dcf0: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
dd00: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
dd10: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
dd20: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
dd30: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
dd40: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
dd50: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
dd60: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
dd70: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
dd80: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
dd90: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
dda0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
ddb0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
ddc0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
ddd0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
dde0: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
ddf0: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
de00: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
de10: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
de20: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
de30: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
de40: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
de50: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
de60: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
de70: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
de80: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
de90: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
dea0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
deb0: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
dec0: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
ded0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
dee0: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
def0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
df00: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
df10: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
df20: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
df30: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
df40: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
df50: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
df60: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
df70: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
df80: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
df90: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
dfa0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
dfb0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
dfc0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
dfd0: 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73  le.  Doing so is
dfe0: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
dff0: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
e000: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
e010: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
e020: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
e030: 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  le.  Because of 
e040: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e050: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e060: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e070: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e080: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e090: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e0a0: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e0b0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e0c0: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e0d0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e0e0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e0f0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e100: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e110: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e120: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e130: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e140: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e150: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e160: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e170: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e180: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e190: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f  E 1" instead.  O
e1a0: 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e  r recompile usin
e1b0: 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
e1c0: 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f  _OMIT_TRUNCATE_O
e1d0: 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d  PTIMIZATION] com
e1e0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e1f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a   to disable the.
e200: 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  ** optimization 
e210: 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a  on all queries..
e220: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
e230: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20  ts:.** [H12241] 
e240: 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12243].**.** I
e250: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
e260: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
e270: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
e280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e290: 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
e2a0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
e2b0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
e2c0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
e2d0: 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
e2e0: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
e2f0: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
e300: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e310: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
e320: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
e330: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
e340: 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
e350: 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  60} <S10600>.**.
e360: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e370: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
e380: 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
e390: 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53  es caused by INS
e3a0: 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f  ERT,.** UPDATE o
e3b0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e3c0: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
e3d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e3e0: 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
e3f0: 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  ** The count inc
e400: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
e410: 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67  s from all trigg
e420: 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  er contexts.  Ho
e430: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
e440: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
e450: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
e460: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52  d to implement R
e470: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
e480: 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
e490: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
e4a0: 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50  cessing, or DROP
e4b0: 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e   table processin
e4c0: 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65  g..** The change
e4d0: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  s are counted as
e4e0: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61   soon as the sta
e4f0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
e500: 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d  s them is.** com
e510: 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
e520: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
e530: 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  e is passed to [
e540: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
e550: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
e560: 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
e570: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
e580: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
e590: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
e5a0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
e5b0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
e5c0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
e5d0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
e5e0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
e5f0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
e600: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
e610: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
e620: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
e630: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
e640: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20  e.)  Because of 
e650: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e660: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e670: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e680: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e690: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e6a0: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e6b0: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e6c0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e6d0: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e6e0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e6f0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e700: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e710: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e720: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e730: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e740: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e750: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e760: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e770: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e780: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e790: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e7a0: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20  E 1" instead.   
e7b0: 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69  Or recompile usi
e7c0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
e7d0: 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f  E_OMIT_TRUNCATE_
e7e0: 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f  OPTIMIZATION] co
e7f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e800: 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  n to disable the
e810: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e820: 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e   on all queries.
e830: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
e840: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
e850: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
e860: 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
e870: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
e880: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
e890: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e8a0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e8b0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e8c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e8d0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e8e0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e8f0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
e900: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
e910: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
e920: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e930: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
e940: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
e950: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e960: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
e970: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
e980: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
e990: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
e9a0: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
e9b0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e9c0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
e9d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
e9e0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
e9f0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
ea00: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
ea10: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
ea20: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
ea30: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
ea40: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
ea50: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
ea60: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
ea70: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
ea80: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
ea90: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
eaa0: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
eab0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
eac0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
ead0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
eae0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
eaf0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
eb00: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
eb10: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
eb20: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
eb30: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
eb40: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
eb50: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
eb60: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
eb70: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
eb80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eb90: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
eba0: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
ebb0: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
ebc0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ebd0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
ebe0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
ebf0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
ec00: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
ec10: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
ec20: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ec30: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
ec40: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ec50: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ec60: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ec70: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
ec80: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ec90: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
eca0: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ecb0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ecc0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ecd0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ece0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
ecf0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
ed00: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
ed10: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ed20: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
ed30: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
ed40: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
ed50: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
ed60: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
ed70: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
ed80: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
ed90: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
eda0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
edb0: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
edc0: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
edd0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
ede0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
edf0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
ee00: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
ee10: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ee20: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d  nts:.** [H12271]
ee30: 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20   [H12272].**.** 
ee40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
ee50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
ee60: 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
ee70: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
ee80: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
ee90: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
eea0: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
eeb0: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
eec0: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
eed0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
eee0: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
eef0: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
ef00: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
ef10: 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
ef20: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
ef30: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
ef40: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
ef50: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
ef60: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
ef70: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
ef80: 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
ef90: 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
efa0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
efb0: 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
efc0: 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
efd0: 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
efe0: 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
eff0: 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
f000: 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
f010: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
f020: 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
f030: 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
f040: 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
f050: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
f060: 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
f070: 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
f080: 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
f090: 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
f0a0: 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
f0b0: 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
f0c0: 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
f0d0: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
f0e0: 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
f0f0: 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
f100: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
f110: 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
f120: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
f130: 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
f140: 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
f150: 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
f160: 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
f170: 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
f180: 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
f190: 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
f1a0: 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
f1b0: 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
f1c0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
f1d0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f1e0: 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
f1f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
f200: 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
f210: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
f220: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
f230: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  t SQL..**.** Req
f240: 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35  uirements: [H105
f250: 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a  11] [H10512].**.
f260: 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
f270: 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
f280: 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
f290: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
f2a0: 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
f2b0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
f2c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
f2d0: 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
f2e0: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
f2f0: 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
f300: 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
f310: 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
f320: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f330: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
f340: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
f350: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
f360: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
f370: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
f380: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
f390: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
f3a0: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
f3b0: 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30  {H12310} <S40400
f3c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
f3d0: 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
f3e0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
f3f0: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
f400: 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
f410: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
f420: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
f430: 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
f440: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
f450: 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
f460: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
f470: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f480: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
f490: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
f4a0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
f4b0: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
f4c0: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
f4d0: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
f4e0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
f4f0: 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
f500: 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
f510: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
f520: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
f530: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
f540: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
f550: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f560: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
f570: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
f580: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
f590: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
f5a0: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
f5b0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
f5c0: 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
f5d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f5e0: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
f5f0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
f600: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
f610: 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
f620: 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
f630: 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
f640: 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
f650: 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
f660: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
f670: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
f680: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
f690: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
f6a0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
f6b0: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
f6c0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f6d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f6e0: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
f6f0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
f700: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
f710: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
f720: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
f730: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
f740: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
f750: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
f760: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
f770: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
f780: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
f790: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
f7a0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
f7b0: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
f7c0: 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
f7d0: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
f7e0: 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
f7f0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
f800: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
f810: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
f820: 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
f830: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
f840: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
f850: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
f860: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
f870: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
f880: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
f890: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
f8a0: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
f8b0: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
f8c0: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
f8d0: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
f8e0: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
f8f0: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
f900: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
f910: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
f920: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
f930: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
f940: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
f950: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
f960: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
f970: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
f980: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
f990: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
f9a0: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
f9b0: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
f9c0: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
f9d0: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
f9e0: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
f9f0: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
fa00: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
fa10: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
fa20: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
fa30: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fa40: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
fa50: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
fa60: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
fa70: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
fa80: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
fa90: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
faa0: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
fab0: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
fac0: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
fad0: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
fae0: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
faf0: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
fb00: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
fb10: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
fb20: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
fb30: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
fb40: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
fb50: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
fb60: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
fb70: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
fb80: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
fb90: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
fba0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
fbb0: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
fbc0: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
fbd0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
fbe0: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
fbf0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
fc00: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
fc10: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
fc20: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
fc30: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
fc40: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
fc50: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
fc60: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
fc70: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
fc80: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
fc90: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
fca0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fcb0: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
fcc0: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
fcd0: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
fce0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
fcf0: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
fd00: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
fd10: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
fd20: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
fd30: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
fd40: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
fd50: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
fd60: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
fd70: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
fd80: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
fd90: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
fda0: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
fdb0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
fdc0: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
fdd0: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
fde0: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
fdf0: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
fe00: 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
fe10: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
fe20: 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
fe30: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
fe40: 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
fe50: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
fe60: 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
fe70: 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
fe80: 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
fe90: 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
fea0: 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
feb0: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
fec0: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
fed0: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
fee0: 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
fef0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ff00: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
ff10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
ff20: 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
ff30: 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
ff40: 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
ff50: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
ff60: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
ff70: 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
ff80: 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
ff90: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
ffa0: 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
ffb0: 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
ffc0: 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
ffd0: 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
ffe0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
fff0: 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
10000 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
10010 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
10020 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
10030 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
10040 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
10050 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
10060 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33  * [H12311] [H123
10070 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31  12] [H12314] [H1
10080 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a  2316] [H12318].*
10090 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64  *.** A busy hand
100a0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
100b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
100c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
100d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
100e0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
100f0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
10100 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
10110 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10120 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
10130 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
10140 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
10150 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
10160 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34  y Timeout {H1234
10170 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
10180 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
10190 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
101a0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
101b0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
101c0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
101d0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
101e0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
101f0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
10200 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a  .  The handler.*
10210 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
10220 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
10230 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
10240 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
10250 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
10260 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48   accumulated. {H
10270 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73  12343} After "ms
10280 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
10290 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
102a0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
102b0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
102c0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
102d0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
102e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
102f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
10300 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
10310 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
10320 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
10330 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
10340 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
10350 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
10360 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
10370 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
10380 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
10390 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
103a0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
103b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
103c0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
103d0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
103e0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
103f0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
10400 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
10410 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10420 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
10430 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
10440 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
10450 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
10460 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
10470 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
10480 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48  :.** [H12341] [H
10490 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a  12343] [H12344].
104a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
104b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
104c0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
104d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
104e0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
104f0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
10500 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30   Queries {H12370
10510 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10000>.**.**
10520 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
10530 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
10540 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
10550 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
10560 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
10570 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10580 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
10590 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
105a0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
105b0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
105c0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
105d0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
105e0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
105f0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
10600 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
10610 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
10620 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
10630 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
10640 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
10650 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
10660 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
10670 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
10680 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
10690 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
106a0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
106b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
106c0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
106d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
106e0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
106f0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
10700 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
10710 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
10720 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
10730 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
10740 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
10750 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
10760 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
10770 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
10780 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
10790 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
107a0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
107b0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
107c0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
107d0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
107e0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
107f0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
10800 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
10810 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
10820 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
10830 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
10840 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
10850 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
10860 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
10870 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
10880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
10890 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
108a0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
108b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
108c0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
108d0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
108e0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
108f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
10900 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
10910 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
10920 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
10930 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
10940 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
10950 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
10960 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
10970 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
10980 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
10990 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
109a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
109b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
109c0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
109d0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
109e0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
109f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
10a00 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
10a10 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
10a20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
10a30 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
10a40 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
10a50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
10a60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
10a70 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
10a80 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
10a90 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
10aa0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
10ab0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
10ac0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
10ad0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
10ae0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
10af0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
10b00 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
10b10 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
10b20 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
10b30 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
10b40 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
10b50 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
10b60 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
10b70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
10b80 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
10b90 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
10ba0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
10bb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10bc0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
10bd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10be0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
10bf0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
10c00 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
10c10 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
10c20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
10c30 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
10c40 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10c50 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
10c60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
10c70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te>.**.** The sq
10c80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10c90 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
10ca0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
10cb0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
10cc0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
10cd0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
10ce0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
10cf0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
10d00 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
10d10 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  er.  It returns 
10d20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
10d30 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
10d40 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
10d50 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
10d60 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c  ** After the cal
10d70 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61  ling function ha
10d80 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
10d90 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20   the result, it 
10da0 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74  should.** pass t
10db0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
10dc0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  e result table t
10dd0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
10de0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
10df0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
10e00 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
10e10 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
10e20 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
10e30 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
10e40 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
10e50 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
10e60 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
10e70 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
10e80 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
10e90 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
10ea0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
10eb0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
10ec0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
10ed0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
10ee0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
10ef0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
10f00 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
10f10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
10f20 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
10f30 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
10f40 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
10f50 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
10f60 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
10f70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10f80 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
10f90 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
10fa0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
10fb0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
10fc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
10fd0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
10fe0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
10ff0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
11000 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
11010 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
11020 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
11030 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
11040 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
11050 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
11060 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
11070 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
11080 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
11090 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
110a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b  _errcode()] or [
110b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
110c0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
110d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37  ments:.** [H1237
110e0 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32  1] [H12373] [H12
110f0 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48  374] [H12376] [H
11100 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a  12379] [H12382].
11110 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
11120 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
11130 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
11140 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
11150 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
11160 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
11170 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
11180 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
11190 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
111a0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
111b0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
111c0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
111d0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
111e0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
111f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
11200 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
11210 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
11220 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
11230 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
11240 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
11250 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
11260 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
11270 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
11280 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11290 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
112a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
112b0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
112c0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
112d0 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d  nctions {H17400}
112e0 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30   <S70000><S20000
112f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
11300 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61  utines are worka
11310 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
11320 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
11330 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
11340 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
11350 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
11360 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70  * The sqlite3_mp
11370 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
11380 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
11390 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
113a0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
113b0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
113c0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
113d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
113e0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
113f0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
11400 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
11410 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
11420 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
11430 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74  e()].  Both rout
11440 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
11450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
11460 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11470 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
11480 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
11490 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
114a0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
114b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
114c0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
114d0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
114e0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
114f0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
11500 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11510 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
11520 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
11530 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
11540 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
11550 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11560 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
11570 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
11580 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11590 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
115a0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
115b0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
115c0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
115d0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
115e0 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
115f0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
11600 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
11610 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
11620 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
11630 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
11640 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
11650 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
11660 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
11670 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
11680 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
11690 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
116a0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
116b0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
116c0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
116d0 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
116e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
116f0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
11700 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
11710 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
11720 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
11730 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
11740 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
11750 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11760 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
11770 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
11780 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
11790 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
117a0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
117b0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
117c0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
117d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
117e0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
117f0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
11800 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
11810 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
11820 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
11830 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
11840 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
11850 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
11860 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
11870 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
11880 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
11890 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
118a0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
118b0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
118c0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
118d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
118e0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
118f0 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
11900 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
11910 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
11920 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
11930 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
11940 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
11950 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
11960 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
11970 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
11980 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
11990 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
119a0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
119b0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
119c0 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
119d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
119e0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
119f0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
11a00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
11a10 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
11a20 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
11a30 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
11a40 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
11a50 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
11a60 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
11a70 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
11a80 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
11a90 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
11aa0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
11ab0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
11ac0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
11ad0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
11ae0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
11af0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
11b00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
11b10 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
11b20 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
11b30 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
11b40 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11b50 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11b60 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
11b70 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
11b80 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
11b90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
11ba0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
11bb0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
11bc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
11bd0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
11be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11bf0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
11c00 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
11c10 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
11c20 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
11c30 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
11c40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
11c50 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
11c60 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
11c70 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
11c80 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11c90 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
11ca0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
11cb0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
11cc0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
11cd0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
11ce0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
11cf0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
11d00 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
11d10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
11d20 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
11d30 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
11d40 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
11d50 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
11d60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11d70 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
11d80 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
11d90 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
11da0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
11db0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
11dc0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
11dd0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
11de0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11df0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
11e00 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
11e10 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
11e20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
11e30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11e40 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
11e50 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
11e60 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
11e70 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
11e80 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
11e90 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
11ea0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
11eb0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
11ec0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
11ed0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
11ee0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
11ef0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
11f00 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
11f10 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
11f20 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
11f30 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
11f40 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
11f50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
11f60 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
11f70 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
11f80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
11f90 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
11fa0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
11fb0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
11fc0 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
11fd0 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
11fe0 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  .  So, for examp
11ff0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
12000 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
12010 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
12020 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
12030 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
12040 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
12050 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
12060 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
12070 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
12080 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
12090 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
120a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
120b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
120c0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
120d0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
120e0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
120f0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
12100 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
12110 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
12120 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
12130 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
12140 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
12150 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
12160 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
12170 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
12180 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
12190 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
121a0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
121b0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
121c0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
121d0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
121e0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
121f0 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
12200 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
12210 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48  :.** [H17403] [H
12220 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a  17406] [H17407].
12230 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
12240 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
12250 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
12260 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
12270 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
12280 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
12290 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
122a0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
122b0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
122c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
122d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
122e0 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30  Subsystem {H1730
122f0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
12300 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
12310 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
12320 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
12330 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
12340 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
12350 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12360 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
12370 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
12380 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
12390 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
123a0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
123b0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
123c0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
123d0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
123e0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
123f0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
12400 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
12410 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12420 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
12430 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
12440 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
12450 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
12460 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
12470 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
12480 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
12490 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  r..** If sqlite3
124a0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
124b0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
124c0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
124d0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
124e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
124f0 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  er.  If the para
12500 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
12510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
12520 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
12530 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
12540 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
12550 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
12560 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  er..**.** Callin
12570 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
12580 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
12590 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
125a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
125b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
125c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
125d0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
125e0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
125f0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
12600 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
12610 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
12620 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
12630 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
12640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
12650 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
12660 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
12670 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
12680 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
12690 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
126a0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
126b0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
126c0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
126d0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
126e0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
126f0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
12700 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
12710 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
12720 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
12730 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
12740 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
12750 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
12760 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
12770 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
12780 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
12790 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
127a0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
127b0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
127c0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
127d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
127e0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
127f0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
12800 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
12810 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
12820 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
12830 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
12840 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12850 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
12860 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
12870 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
12880 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
12890 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
128a0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
128b0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
128c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
128d0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
128e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
128f0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
12900 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
12910 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
12920 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
12930 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
12940 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
12950 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
12960 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
12970 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
12980 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
12990 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
129a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
129b0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
129c0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
129d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
129e0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
129f0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
12a00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
12a10 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
12a20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12a30 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
12a40 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
12a50 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
12a60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12a70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
12a90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
12aa0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
12ab0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
12ac0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
12ad0 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
12ae0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
12af0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
12b00 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
12b10 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
12b20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
12b30 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
12b40 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
12b50 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
12b60 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
12b70 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
12b80 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
12b90 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
12ba0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
12bb0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
12bc0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
12bd0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
12be0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
12bf0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
12c00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
12c10 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
12c20 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
12c30 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
12c40 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
12c50 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
12c60 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
12c70 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
12c80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
12c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ca0 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
12cb0 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
12cc0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
12cd0 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
12ce0 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
12cf0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31   library..** {H1
12d00 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
12d10 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12d20 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
12d30 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
12d40 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
12d50 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d60 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
12d70 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
12d80 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
12d90 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
12da0 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
12db0 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
12dc0 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
12dd0 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
12de0 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
12df0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
12e00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e10 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
12e20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
12e30 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
12e40 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
12e50 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
12e60 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
12e70 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
12e80 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
12e90 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
12ea0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
12eb0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
12ec0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
12ed0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
12ee0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
12ef0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
12f00 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
12f10 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
12f20 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
12f30 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
12f40 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
12f50 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
12f60 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
12f70 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
12f80 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
12f90 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
12fa0 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
12fb0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
12fc0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
12fd0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
12fe0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
12ff0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
13000 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
13010 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
13020 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
13030 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
13040 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
13050 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
13060 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
13070 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13080 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
13090 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
130a0 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
130b0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
130c0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
130d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
130e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
130f0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
13100 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
13110 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30   [H17303] [H1730
13120 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37  4] [H17305] [H17
13130 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48  306] [H17310] [H
13140 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20  17312] [H17315] 
13150 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37  [H17318].** [H17
13160 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48  321] [H17322] [H
13170 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65  17323].**.** The
13180 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
13190 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
131a0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
131b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
131c0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
131d0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
131e0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
131f0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
13200 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
13210 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13220 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
13230 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
13240 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
13250 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
13260 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13270 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
13280 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
13290 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
132a0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
132b0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
132c0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
132d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
132e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
132f0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
13300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
13310 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
13320 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
13330 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
13340 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
13350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13360 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
13370 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
13380 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e  H17370} <S30210>
13390 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
133a0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
133b0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
133c0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
133d0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
133e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
133f0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
13400 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
13410 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
13420 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
13430 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
13440 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
13450 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
13460 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13470 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31  ents:.** [H17371
13480 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33  ] [H17373] [H173
13490 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a  74] [H17375].*/.
134a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
134b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
134c0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
134d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
134e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
134f0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
13500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13510 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
13520 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
13530 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30  {H17390} <S20000
13540 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
13550 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
13560 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
13570 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
13580 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
13590 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
135a0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
135b0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
135c0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
135d0 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
135e0 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
135f0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
13600 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
13610 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
13620 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
13630 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
13640 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
13650 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
13660 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
13670 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
13680 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
13690 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
136a0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
136b0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  urposes..**.** A
136c0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
136d0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
136e0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
136f0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
13700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
13710 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
13720 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
13730 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
13740 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
13750 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
13760 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
13770 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
13780 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
13790 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
137a0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
137b0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
137c0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
137d0 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
137e0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
137f0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
13800 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
13810 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
13820 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
13830 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
13840 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
13850 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
13860 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
13870 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d  nts:.** [H17392]
13880 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
13890 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
138a0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
138b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
138c0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
138d0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
138e0 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30  ks {H12500} <S70
138f0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100>.**.** This 
13900 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
13910 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
13920 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
13930 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
13940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13950 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
13960 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13970 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
13980 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
13990 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
139a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
139b0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
139c0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
139d0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
139e0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
139f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
13a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
13a10 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
13a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
13a30 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
13a40 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
13a50 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
13a60 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
13a70 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
13a80 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
13a90 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
13aa0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
13ab0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
13ac0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
13ad0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
13ae0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
13af0 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
13b00 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
13b10 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
13b20 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
13b30 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
13b40 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
13b50 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
13b60 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
13b70 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
13b80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
13b90 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
13ba0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
13bb0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
13bc0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
13bd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
13be0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
13bf0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
13c00 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
13c10 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13c20 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
13c30 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
13c40 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
13c50 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
13c60 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
13c70 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
13c80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
13c90 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
13ca0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
13cb0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
13cc0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
13cd0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
13ce0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
13cf0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13d00 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
13d10 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
13d20 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
13d30 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
13d40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
13d50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
13d60 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
13d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
13d80 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
13d90 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
13da0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
13db0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
13dc0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
13dd0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
13de0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
13df0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
13e00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
13e10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
13e20 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
13e30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13e40 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
13e50 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
13e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13e70 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
13e80 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
13e90 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
13ea0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
13eb0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
13ec0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
13ed0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
13ee0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
13ef0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
13f00 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
13f10 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
13f20 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
13f30 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
13f40 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
13f50 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
13f60 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
13f70 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
13f80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13f90 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
13fa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
13fb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
13fc0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
13fd0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
13fe0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
13ff0 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
14000 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
14010 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
14020 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
14030 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
14040 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
14050 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14060 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
14070 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
14080 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
14090 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
140a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
140b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
140c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
140d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
140e0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
140f0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
14100 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
14110 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
14120 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
14130 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
14140 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14150 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
14160 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14170 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
14180 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
14190 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
141a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
141b0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
141c0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
141d0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
141e0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
141f0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
14200 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
14210 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
14220 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
14230 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
14240 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
14250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
14260 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
14270 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
14280 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
14290 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
142a0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
142b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
142c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
142d0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
142e0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
142f0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
14300 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
14310 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
14320 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
14330 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
14340 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
14350 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
14360 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
14370 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
14380 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
14390 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
143a0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
143b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
143c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
143d0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
143e0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
143f0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
14400 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
14410 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
14420 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
14430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
14440 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
14450 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
14460 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
14470 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
14480 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
14490 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
144a0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
144b0 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
144c0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
144d0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
144e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
144f0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
14500 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
14510 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
14520 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
14530 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
14540 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
14550 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
14560 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
14570 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
14580 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
14590 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
145a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
145b0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
145c0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
145d0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
145e0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
145f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
14600 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
14610 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
14620 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
14630 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
14640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
14650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
14660 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
14670 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
14680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14690 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
146a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
146b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
146c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71  ..**.** When [sq
146d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
146e0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
146f0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
14700 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
14710 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
14720 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
14730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14740 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
14750 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
14760 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
14770 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
14780 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
14790 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
147a0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
147b0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
147c0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
147d0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  step()]..**.** N
147e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
147f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14800 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
14810 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
14820 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
14830 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
14840 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
14850 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
14860 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
14870 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
14880 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
14890 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
148a0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
148b0 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31  01] [H12502] [H1
148c0 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b  2503] [H12504] [
148d0 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d  H12505] [H12506]
148e0 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31   [H12507] [H1251
148f0 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b  0].** [H12511] [
14900 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d  H12512] [H12520]
14910 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32   [H12521] [H1252
14920 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
14930 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14940 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
14950 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
14960 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14970 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
14980 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
14990 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
149a0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
149b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
149c0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
149d0 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
149e0 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
149f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
14a00 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
14a10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14a20 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
14a30 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
14a40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
14a50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
14a60 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
14a70 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
14a80 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
14a90 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
14aa0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
14ab0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
14ac0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14ad0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
14ae0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
14af0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
14b00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
14b10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14b20 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
14b30 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
14b40 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
14b50 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
14b60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
14b70 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
14b80 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
14b90 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
14ba0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
14bb0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
14bc0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
14bd0 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
14be0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
14bf0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
14c00 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
14c10 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
14c20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
14c30 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
14c40 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
14c50 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
14c60 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
14c70 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
14c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
14c90 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
14ca0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
14cb0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
14cc0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
14cd0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
14ce0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
14cf0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
14d00 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
14d10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14d20 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
14d30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
14d40 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
14d50 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
14d60 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
14d70 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
14d80 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
14d90 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
14da0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
14db0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
14dc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
14dd0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
14de0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
14df0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
14e00 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
14e10 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
14e20 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
14e30 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
14e40 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
14e50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
14e60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
14e70 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
14e80 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
14e90 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
14ea0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
14eb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
14ec0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14ed0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
14ee0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
14ef0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
14f00 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
14f10 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
14f20 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
14f30 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
14f40 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
14f50 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
14f60 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
14f70 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  L code..**.** Re
14f80 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
14f90 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d  H12551] [H12552]
14fa0 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35   [H12553] [H1255
14fb0 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  4].*/./*********
14fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14fe0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
14ff0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
15000 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
15010 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
15020 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
15030 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
15040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15060 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
15070 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
15080 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15090 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
150a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
150b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
150c0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
150d0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
150e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
150f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15100 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
15110 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
15120 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15130 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15150 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
15160 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
15170 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
15180 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
151a0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
151b0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
151c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
151d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
151e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
151f0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
15200 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
15210 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
15220 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
15230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15240 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
15250 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
15260 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
15270 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15280 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
15290 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
152a0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
152b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
152c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
152d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
152e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
152f0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
15300 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
15310 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15320 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15330 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
15340 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
15350 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15360 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15370 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
15380 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
15390 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
153a0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
153b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
153c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
153d0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
153e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
153f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15410 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15420 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
15430 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
15440 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15460 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15470 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
15480 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
15490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
154a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
154b0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
154c0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
154d0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
154e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
154f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15500 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
15510 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
15520 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
15530 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15550 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
15560 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
15570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
155a0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
155b0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
155c0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
155d0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
155e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
155f0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
15600 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
15610 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
15620 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
15630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15640 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
15650 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
15660 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
15670 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
15690 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
156a0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
156b0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
156c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
156d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
156e0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
156f0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
15700 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
15710 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
15720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
15730 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
15740 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
15750 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
15760 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
15770 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
15780 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
15790 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
157a0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
157b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
157c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
157d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
157e0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
157f0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
15800 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15810 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
15820 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
15830 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
15840 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15850 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15860 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
15870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
15880 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15890 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
158a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
158b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
158c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
158d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
158e0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
158f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15900 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
15910 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
15920 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15930 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
15940 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15950 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
15960 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
15970 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
15980 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
15990 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
159a0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
159b0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
159c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
159d0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
159e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
159f0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
15a00 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
15a10 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
15a20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15a30 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
15a40 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
15a50 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
15a60 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
15a70 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
15a80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
15a90 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
15aa0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
15ab0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
15ac0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
15ad0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
15ae0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
15af0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
15b00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15b10 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
15b20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
15b30 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
15b40 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
15b50 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
15b60 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
15b70 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
15b80 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
15b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
15ba0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
15bb0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
15bc0 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
15bd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
15be0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
15bf0 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
15c00 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
15c10 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
15c20 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
15c30 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
15c40 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
15c50 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
15c60 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
15c70 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
15c80 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
15c90 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
15ca0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15cb0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
15cc0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
15cd0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
15ce0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
15cf0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
15d00 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
15d10 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
15d20 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
15d30 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
15d40 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
15d50 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
15d60 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
15d70 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
15d80 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
15d90 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
15da0 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31  .** [H12281] [H1
15db0 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b  2282] [H12283] [
15dc0 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d  H12284] [H12285]
15dd0 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38   [H12287] [H1228
15de0 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b  8] [H12289].** [
15df0 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54  H12290].*/.SQLIT
15e00 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
15e10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
15e20 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
15e30 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
15e40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
15e50 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
15e60 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
15e70 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
15e80 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
15e90 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
15ea0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
15eb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
15ec0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
15ed0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
15ee0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
15ef0 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
15f00 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
15f10 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
15f20 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
15f30 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
15f40 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
15f50 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
15f60 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
15f70 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
15f80 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
15f90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
15fa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
15fb0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
15fc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
15fd0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
15fe0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
15ff0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
16000 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
16010 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
16020 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
16030 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
16040 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
16050 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
16060 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
16070 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
16080 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
16090 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
160a0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
160b0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
160c0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
160d0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
160e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
160f0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
16100 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
16110 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
16120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
16130 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
16140 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
16150 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
16160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16170 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
16180 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
16190 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
161a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
161b0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
161c0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
161d0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
161e0 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ph..**.** Requir
161f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
16200 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31  11] [H12912] [H1
16210 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b  2913] [H12914] [
16220 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d  H12915] [H12916]
16230 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31   [H12917] [H1291
16240 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  8].**.*/.void sq
16250 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
16260 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
16270 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
16280 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
16290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
162a0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
162b0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
162c0 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
162d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
162e0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
162f0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
16300 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
16310 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
16320 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
16330 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
16340 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
16350 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
16360 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
16370 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
16380 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
16390 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
163a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
163b0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
163c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
163d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
163e0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
163f0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
16400 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
16410 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
16420 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
16430 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
16440 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
16450 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
16460 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
16470 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
16480 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
16490 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
164a0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
164b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
164c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
164d0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
164e0 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
164f0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
16500 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
16510 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
16520 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
16530 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
16540 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
16550 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
16560 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
16570 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
16580 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
16590 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
165a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
165b0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
165c0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
165d0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
165e0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
165f0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
16600 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
16610 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
16620 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
16630 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
16640 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
16650 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
16660 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
16670 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
16680 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
16690 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
166a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
166b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
166c0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
166d0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
166e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
166f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16700 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
16710 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
16720 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
16730 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
16740 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
16750 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
16760 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
16770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16780 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
16790 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
167a0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
167b0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
167c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
167d0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
167e0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
167f0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
16800 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
16810 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
16820 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
16830 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
16840 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
16850 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
16860 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
16870 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
16880 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
16890 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
168a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
168b0 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  gs:.**.** <dl>.*
168c0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
168d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
168e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
168f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
16900 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
16910 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
16920 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
16930 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
16940 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
16950 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
16960 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
16970 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
16980 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
16990 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
169a0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
169b0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
169c0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
169d0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
169e0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
169f0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
16a00 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
16a10 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
16a20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
16a30 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
16a40 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
16a50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
16a60 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
16a70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
16a80 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
16a90 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
16aa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
16ab0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
16ac0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
16ad0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
16ae0 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
16af0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
16b00 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
16b10 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
16b20 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
16b30 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
16b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
16b50 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
16b60 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
16b70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
16b80 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
16b90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16ba0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
16bb0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
16bc0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
16bd0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
16be0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
16bf0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
16c00 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
16c10 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
16c20 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
16c30 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
16c40 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
16c50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
16c60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
16c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16c80 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
16c90 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
16ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16cb0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
16cc0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
16cd0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
16ce0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
16cf0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
16d00 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
16d10 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
16d20 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
16d30 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a  t-time.  If the.
16d40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
16d50 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
16d60 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
16d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16d80 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
16d90 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
16da0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
16db0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
16dc0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
16dd0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
16de0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
16df0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
16e00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
16e10 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
16e20 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
16e30 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
16e40 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
16e50 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
16e60 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
16e70 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
16e80 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
16e90 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
16ea0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16eb0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
16ec0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
16ed0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
16ee0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
16ef0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
16f00 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
16f10 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
16f20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
16f30 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
16f40 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
16f50 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
16f60 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
16f70 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
16f80 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
16f90 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
16fa0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
16fb0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
16fc0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
16fd0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
16fe0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
16ff0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
17000 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
17010 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
17020 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
17030 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
17040 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
17050 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
17060 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
17070 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
17080 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
17090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
170a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
170b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
170c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
170d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
170e0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
170f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
17100 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
17110 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
17120 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
17130 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
17140 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
17150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
17160 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
17170 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17180 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
17190 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
171a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
171b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
171c0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
171d0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
171e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
171f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
17200 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
17210 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
17220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
17230 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
17240 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
17250 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
17260 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
17270 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17280 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
17290 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
172a0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
172b0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
172c0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
172d0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
172e0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
172f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
17300 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
17310 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
17320 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31  ents:.** [H12701
17330 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32 37  ] [H12702] [H127
17340 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48 31  03] [H12704] [H1
17350 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b  2706] [H12707] [
17360 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31 5d  H12709] [H12711]
17370 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48 31  .** [H12712] [H1
17380 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b  2713] [H12714] [
17390 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39 5d  H12717] [H12719]
173a0 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37 32   [H12721] [H1272
173b0 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  3].*/.int sqlite
173c0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
173d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
173e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
173f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
17400 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
17410 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
17420 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
17430 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
17440 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
17450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
17460 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
17470 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
17480 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
17490 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
174a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
174b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
174c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
174d0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
174e0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
174f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
17500 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
17510 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
17520 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
17530 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
17540 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
17550 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
17560 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
17570 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
17580 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
17590 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
175a0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
175b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
175c0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
175d0 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53  ages {H12800} <S
175e0 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60200>.**.** The
175f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
17600 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
17610 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
17620 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
17630 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
17640 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
17650 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17660 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
17670 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
17680 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
17690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
176a0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
176b0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
176c0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
176d0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
176e0 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
176f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
17700 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
17710 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
17720 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ned.  The sqlite
17730 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
17740 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
17750 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
17760 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
17770 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
17780 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
17790 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
177a0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
177b0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
177c0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
177d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
177e0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
177f0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
17800 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
17810 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
17820 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
17830 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
17840 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
17850 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
17860 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
17870 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
17880 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
17890 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
178a0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
178b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
178c0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
178d0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
178e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
178f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
17900 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
17910 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
17920 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
17930 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
17940 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
17950 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
17960 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  s..**.** When th
17970 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
17980 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
17990 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
179a0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
179b0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
179c0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
179d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
179e0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
179f0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
17a00 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
17a10 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
17a20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
17a30 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
17a40 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
17a50 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
17a60 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
17a70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
17a80 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
17a90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
17aa0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
17ab0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
17ac0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
17ad0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
17ae0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17af0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
17b00 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
17b10 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
17b20 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
17b30 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
17b40 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
17b50 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
17b60 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
17b70 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
17b80 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
17b90 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
17ba0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
17bb0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
17bc0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
17bd0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
17be0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
17bf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
17c00 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
17c10 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
17c20 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
17c30 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
17c40 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
17c50 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
17c60 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
17c70 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
17c80 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ot be set..**.**
17c90 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
17ca0 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32 38  * [H12801] [H128
17cb0 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48 31  02] [H12803] [H1
17cc0 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b  2807] [H12808] [
17cd0 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12809].*/.int s
17ce0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
17cf0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
17d00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
17d10 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
17d20 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
17d30 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
17d40 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
17d50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
17d60 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
17d70 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17d80 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
17d90 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
17da0 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a  000} <H13010>.**
17db0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
17dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
17dd0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
17de0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
17df0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
17e00 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
17e10 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
17e20 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
17e30 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
17e40 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
17e50 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
17e60 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
17e70 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
17e80 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
17e90 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
17ea0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
17eb0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
17ec0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
17ed0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
17ee0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
17ef0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
17f00 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
17f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17f20 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
17f30 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
17f40 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
17f50 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
17f60 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
17f70 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
17f80 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
17f90 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
17fa0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
17fb0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
17fc0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
17fd0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
17fe0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
17ff0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
18000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
18010 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
18020 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
18030 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
18040 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
18050 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
18060 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
18070 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18080 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
18090 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
180a0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
180b0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
180c0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
180d0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
180e0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
180f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
18100 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
18110 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
18120 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
18130 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53  mits {H12760} <S
18140 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20600>.**.** Thi
18150 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
18160 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
18170 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
18180 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
18190 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
181a0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
181b0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
181c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
181d0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
181e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
181f0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
18200 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
18210 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
18230 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
18240 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
18250 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
18260 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
18270 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
18280 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
18290 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
182a0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
182b0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
182c0 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
182d0 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
182e0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
182f0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
18300 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
18310 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
18320 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
18330 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
18340 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
18350 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
18360 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
18370 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
18380 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61  und].** set by a
18390 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
183a0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
183b0 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69  ro named .** [li
183c0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
183d0 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20  X_XYZ]..** (The 
183e0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
183f0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
18400 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
18410 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
18420 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
18430 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
18440 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
18450 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
18460 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
18470 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
18480 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
18490 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
184a0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
184b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
184c0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
184d0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
184e0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
184f0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
18500 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
18510 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
18520 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
18530 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
18540 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
18550 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
18560 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
18570 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
18580 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
18590 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
185a0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
185b0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
185c0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
185d0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
185e0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
185f0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
18600 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
18610 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
18620 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
18630 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
18640 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
18650 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
18660 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
18670 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
18680 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
18690 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
186a0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
186b0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
186c0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
186d0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
186e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
186f0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18700 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
18710 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
18720 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
18730 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
18740 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
18750 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
18760 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
18770 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
18780 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
18790 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
187a0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
187b0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
187c0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
187d0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
187e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
187f0 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31  .** [H12762] [H1
18800 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a  2766] [H12769].*
18810 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
18820 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
18830 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
18840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18850 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
18860 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48  it Categories {H
18870 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a  12790} <H12760>.
18880 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
18890 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c  mit category} {l
188a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
188b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
188c0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
188d0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
188e0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
188f0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
18900 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
18910 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
18920 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
18930 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
18940 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
18950 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
18960 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
18970 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
18980 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
18990 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
189a0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
189b0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
189c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
189d0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
189e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
189f0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
18a00 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
18a10 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
18a20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18a30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
18a40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18a50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
18a60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18a70 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
18a80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
18a90 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
18aa0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18ab0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
18ac0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
18ad0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
18ae0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
18af0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
18b00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18b10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
18b20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
18b30 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
18b40 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
18b50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18b60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
18b70 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
18b80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18b90 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
18ba0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
18bb0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
18bc0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18bd0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
18be0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
18bf0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18c00 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
18c10 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
18c20 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
18c30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18c40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
18c50 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
18c60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18c70 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
18c80 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
18c90 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
18ca0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
18cb0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
18cc0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18cd0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18ce0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
18cf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18d00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18d10 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
18d20 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
18d30 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18d40 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
18d50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18d60 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18d70 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
18d80 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
18d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
18db0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
18dc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18dd0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
18de0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
18df0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
18e00 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
18e10 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
18e20 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18e30 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
18e40 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
18e50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18e60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
18e70 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
18e80 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
18e90 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
18ea0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
18eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ec0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
18ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18ee0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
18ef0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
18f00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18f10 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
18f20 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
18f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f40 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
18f50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
18f60 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
18f70 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18f80 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
18f90 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
18fa0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
18fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
18fc0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
18fd0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
18fe0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
18ff0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
19000 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
19010 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
19020 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
19030 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
19040 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
19050 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
19060 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
19070 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
19080 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
19090 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
190a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
190b0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
190c0 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20  tement {H13010} 
190d0 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10000>.** KEYW
190e0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
190f0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
19100 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
19110 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
19120 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
19130 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
19140 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
19150 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
19160 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
19170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
19180 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
19190 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
191a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
191b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
191c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
191d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
191e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
191f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
19200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
19210 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
19220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19230 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
19240 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
19250 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
19260 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
19270 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
19280 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
19290 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
192a0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
192b0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
192c0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
192d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
192e0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
192f0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
19300 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
19310 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
19320 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19330 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
19340 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
19350 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
19360 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
19370 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
19380 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
19390 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
193a0 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69  ator. If nByte i
193b0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
193c0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
193d0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
193e0 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
193f0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
19400 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
19410 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
19420 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
19430 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
19440 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
19450 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
19460 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
19470 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
19480 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
19490 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
194a0 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
194b0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
194c0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
194d0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
194e0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
194f0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
19500 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
19510 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
19520 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
19530 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
19540 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
19550 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
19560 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
19570 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
19580 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
19590 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66   bytes..**.** If
195a0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
195b0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
195c0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
195d0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
195e0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
195f0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
19600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
19610 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
19620 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
19630 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
19640 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
19650 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
19660 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
19670 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
19680 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
19690 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73  **.** *ppStmt is
196a0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
196b0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
196c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
196d0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
196e0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
196f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19700 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61  .  If there is a
19710 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
19720 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
19730 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
19740 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
19750 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
19760 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
19770 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
19780 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
19790 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
197a0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
197b0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
197c0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
197d0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
197e0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
197f0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
19800 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
19810 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
19820 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
19830 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
19840 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
19850 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
19860 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
19870 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
19880 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
19890 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
198a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
198b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
198c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
198d0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
198e0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
198f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
19900 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
19910 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
19920 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
19930 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
19940 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19950 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
19960 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
19970 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
19980 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
19990 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
199a0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
199b0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
199c0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
199d0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
199e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
199f0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
19a00 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
19a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19a20 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
19a30 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
19a40 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
19a50 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
19a60 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
19a70 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
19a80 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
19a90 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
19aa0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
19ab0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
19ac0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
19ad0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
19ae0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
19af0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
19b00 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
19b10 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
19b20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
19b30 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
19b40 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
19b50 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
19b60 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
19b70 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
19b80 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
19b90 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
19ba0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
19bb0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
19bc0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
19bd0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19be0 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
19bf0 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
19c00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
19c10 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
19c20 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
19c30 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
19c40 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
19c50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
19c60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
19c70 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
19c80 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
19c90 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
19ca0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
19cb0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
19cc0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
19cd0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
19ce0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
19cf0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
19d00 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
19d10 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
19d20 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
19d30 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
19d40 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
19d50 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
19d60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19d70 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
19d80 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
19d90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
19da0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
19db0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
19dc0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
19dd0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
19de0 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
19df0 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
19e00 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
19e10 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
19e20 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
19e30 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
19e40 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
19e50 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
19e60 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
19e70 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
19e80 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
19e90 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  </ol>.**.** Requ
19ea0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
19eb0 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20 5b  3011] [H13012] [
19ec0 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34 5d  H13013] [H13014]
19ed0 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30 31   [H13015] [H1301
19ee0 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31 33  6] [H13019] [H13
19ef0 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73  021].**.*/.int s
19f00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
19f10 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
19f20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
19f30 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
19f40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
19f50 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
19f60 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
19f70 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
19f80 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
19f90 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
19fa0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
19fb0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
19fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
19fd0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
19fe0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
19ff0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a000 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1a010 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1a020 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1a030 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1a040 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1a050 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1a060 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1a070 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1a080 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1a090 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1a0a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1a0b0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1a0c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a0e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a0f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a100 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a110 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a120 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a130 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a140 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1a150 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a160 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a170 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a180 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1a190 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1a1a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1a1b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1a1c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a1d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1a1e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1a1f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1a200 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1a210 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1a220 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1a230 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1a240 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1a250 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1a260 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1a270 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1a280 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1a290 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1a2a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1a2b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1a2c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1a2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a2e0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1a2f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1a300 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1a310 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1a320 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1a330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1a340 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1a350 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1a360 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1a370 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1a380 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1a390 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1a3a0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1a3b0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1a3c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a3d0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1a3e0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1a3f0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1a400 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1a410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a420 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
1a430 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31  tatement SQL {H1
1a440 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a  3100} <H13000>.*
1a450 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1a460 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
1a470 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
1a480 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
1a490 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
1a4a0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
1a4b0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
1a4c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
1a4d0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
1a4e0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
1a4f0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1a500 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a510 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1a520 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1a530 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1a540 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48  :.** [H13101] [H
1a550 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a  13102] [H13103].
1a560 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1a570 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1a580 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1a590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a5a0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
1a5b0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
1a5c0 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30   {H15000} <S2020
1a5d0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1a5e0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
1a5f0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
1a600 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a610 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
1a620 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
1a630 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1a640 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
1a650 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
1a660 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
1a670 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
1a680 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
1a690 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
1a6a0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
1a6b0 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75   it stores. Valu
1a6c0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1a6d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a6e0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
1a6f0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
1a700 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
1a710 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
1a720 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
1a730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1a740 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
1a750 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
1a760 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
1a770 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
1a780 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
1a790 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a7a0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
1a7b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
1a7c0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
1a7d0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
1a7e0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1a7f0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
1a800 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
1a810 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
1a820 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
1a830 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
1a840 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1a850 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
1a860 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a870 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
1a880 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
1a890 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
1a8a0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
1a8b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
1a8c0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
1a8d0 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74    A internal mut
1a8e0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1a8f0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
1a900 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a910 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
1a920 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
1a930 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1a940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a950 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
1a960 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
1a970 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
1a980 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
1a990 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
1a9a0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1a9b0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1a9c0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1a9d0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
1a9e0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
1a9f0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
1aa00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
1aa10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1aa20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
1aa30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1aa40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
1aa50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1aa60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1aa70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1aa80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1aa90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1aaa0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
1aab0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1aac0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
1aad0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1aae0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
1aaf0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1ab00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1ab10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
1ab20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
1ab30 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70  etween between p
1ab40 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1ab50 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1ab60 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ab70 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
1ab80 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
1ab90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1aba0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1abb0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1abc0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1abd0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1abe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1abf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ac00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ac10 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1ac20 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1ac30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1ac40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1ac50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1ac60 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1ac70 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1ac80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ac90 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1aca0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1acb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1acc0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1acd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1ace0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1acf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1ad00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1ad10 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1ad20 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1ad30 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1ad40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ad50 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1ad60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1ad70 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1ad80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ad90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1ada0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b  Context Object {
1adb0 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e  H16001} <S20200>
1adc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
1add0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
1ade0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
1adf0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
1ae00 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
1ae10 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
1ae20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
1ae30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ae40 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1ae50 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1ae60 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1ae70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1ae80 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1ae90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1aea0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1aeb0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1aec0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1aed0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1aee0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1aef0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1af00 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1af10 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1af20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1af30 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1af40 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1af50 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1af60 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1af70 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1af80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1af90 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1afa0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1afb0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1afc0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1afd0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1afe0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1aff0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1b000 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1b010 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48  ed Statements {H
1b020 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13500} <S70300>.
1b030 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1b040 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1b050 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1b060 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1b070 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1b080 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1b090 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1b0a0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1b0b0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e  inding}.**.** In
1b0c0 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
1b0d0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1b0e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b0f0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1b100 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
1b110 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
1b120 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
1b130 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  in one of these 
1b140 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  forms:.**.** <ul
1b150 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1b160 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1b170 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1b180 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1b190 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1b1a0 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d  .** In the param
1b1b0 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e  eter forms shown
1b1c0 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e   above NNN is an
1b1d0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
1b1e0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20  ,.** and VVV is 
1b1f0 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63  an alpha-numeric
1b200 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e   parameter name.
1b210 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
1b220 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
1b230 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1b240 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1b250 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
1b260 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1b270 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1b280 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b290 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1b2a0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1b2b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1b2c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1b2d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b2e0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1b2f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1b300 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1b310 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1b320 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1b330 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b340 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1b350 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  s..**.** The sec
1b360 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1b370 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1b380 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1b390 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65  o be set..** The
1b3a0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
1b3b0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
1b3c0 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e  ndex of 1.  When
1b3d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
1b3e0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
1b3f0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
1b400 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
1b410 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
1b420 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
1b430 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
1b440 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
1b450 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68  ccurrence..** Th
1b460 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
1b470 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
1b480 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
1b490 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
1b4a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b4b0 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
1b4c0 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
1b4d0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
1b4e0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
1b4f0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
1b500 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20  NNN..** The NNN 
1b510 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1b520 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1b530 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1b540 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1b550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1b560 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1b570 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1b580 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1b590 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1b5a0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1b5b0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1b5c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1b5d0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
1b5e0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
1b5f0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
1b600 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1b610 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1b620 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
1b630 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
1b640 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
1b650 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1b660 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
1b670 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
1b680 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1b690 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  rs..** If the fo
1b6a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1b6b0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
1b6c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
1b6d0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
1b6e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1b6f0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1b700 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1b710 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
1b720 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1b730 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1b740 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1b750 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1b760 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1b770 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1b780 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1b790 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1b7a0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1b7b0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1b7c0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
1b7d0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b7e0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1b7f0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1b800 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1b810 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1b820 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1b830 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1b840 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1b850 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1b860 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1b870 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
1b880 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1b890 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1b8a0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1b8b0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1b8c0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1b8d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1b8e0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1b8f0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1b900 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1b910 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1b920 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
1b930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1b940 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1b950 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1b960 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1b970 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1b980 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c  eroes.  A zerobl
1b990 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1b9a0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1b9b0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1b9c0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
1b9d0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
1b9e0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
1b9f0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
1ba00 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
1ba10 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
1ba20 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
1ba30 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
1ba40 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
1ba50 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
1ba60 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1ba70 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
1ba80 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
1ba90 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76  .** A negative v
1baa0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
1bab0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
1bac0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
1bad0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  LOB..**.** The s
1bae0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1baf0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
1bb00 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a   called after.**
1bb10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bb20 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73  e_v2()] (and its
1bb30 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73   variants) or [s
1bb40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1bb50 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73  and.** before [s
1bb60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1bb70 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20  ** Bindings are 
1bb80 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1bb90 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1bba0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1bbb0 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74   Unbound paramet
1bbc0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
1bbd0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
1bbe0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1bbf0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1bc00 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
1bc10 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  or an error code
1bc20 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20   if.** anything 
1bc30 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51  goes wrong.  [SQ
1bc40 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
1bc50 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
1bc60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
1bc70 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
1bc80 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  e.  [SQLITE_NOME
1bc90 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
1bca0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
1bcb0 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ..** [SQLITE_MIS
1bcc0 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65  USE] might be re
1bcd0 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20  turned if these 
1bce0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
1bcf0 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74  led on a.** virt
1bd00 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74  ual machine that
1bd10 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74   is the wrong st
1bd20 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73  ate or which has
1bd30 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69   already been fi
1bd40 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65  nalized..** Dete
1bd50 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20  ction of misuse 
1bd60 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20  is unreliable.  
1bd70 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
1bd80 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a  uld not depend.*
1bd90 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  * on SQLITE_MISU
1bda0 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c  SE returns.  SQL
1bdb0 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e  ITE_MISUSE is in
1bdc0 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61  tended to indica
1bdd0 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20  te a.** a logic 
1bde0 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70  error in the app
1bdf0 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72  lication.  Futur
1be00 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1be10 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61  Lite might.** pa
1be20 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20  nic rather than 
1be30 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
1be40 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  SUSE..**.** See 
1be50 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1be60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1be70 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
1be80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1be90 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
1bea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1beb0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1bec0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1bed0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36  ents:.** [H13506
1bee0 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35  ] [H13509] [H135
1bef0 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31  12] [H13515] [H1
1bf00 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b  3518] [H13521] [
1bf10 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d  H13524] [H13527]
1bf20 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31  .** [H13530] [H1
1bf30 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b  3533] [H13536] [
1bf40 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d  H13539] [H13542]
1bf50 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34   [H13545] [H1354
1bf60 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a  8] [H13551].**.*
1bf70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1bf80 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
1bf90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1bfa0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
1bfb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1bfc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1bfd0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
1bfe0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
1bff0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
1c000 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
1c010 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1c020 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1c030 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
1c040 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
1c060 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1c070 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
1c080 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
1c090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c0a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c0b0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
1c0c0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1c0d0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1c0e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1c0f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1c100 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1c110 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
1c120 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1c130 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1c140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1c150 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
1c160 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
1c170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1c180 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1c190 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
1c1a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c1b0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
1c1c0 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36  Parameters {H136
1c1d0 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  00} <S70300>.**.
1c1e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1c1f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
1c200 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1c210 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
1c220 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
1c230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1c240 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
1c250 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
1c260 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
1c270 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
1c280 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
1c290 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
1c2a0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
1c2b0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
1c2c0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
1c2d0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
1c2e0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
1c2f0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
1c300 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  time..**.** This
1c310 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1c320 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1c330 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1c340 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
1c350 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
1c360 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1c370 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1c380 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1c390 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1c3a0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1c3b0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1c3c0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61  rs of the ?NNN a
1c3d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
1c3e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
1c3f0 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a   the list..**.**
1c400 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1c410 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1c420 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1c430 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1c440 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1c450 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1c460 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c470 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1c480 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1c490 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a 69  ** [H13601].*/.i
1c4a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1c4b0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1c4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
1c4d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c4e0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
1c4f0 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32  Parameter {H1362
1c500 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1c510 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
1c520 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1c530 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   to the name of 
1c540 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c  the n-th.** [SQL
1c550 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61   parameter] in a
1c560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1c570 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61  ment]..** SQL pa
1c580 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1c590 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
1c5a0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1c5b0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
1c5c0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
1c5d0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
1c5e0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1c5f0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1c600 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
1c610 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
1c620 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
1c630 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
1c640 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
1c650 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
1c660 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
1c670 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
1c680 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
1c690 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
1c6a0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
1c6b0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
1c6c0 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74   also referred t
1c6d0 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  o as "anonymous 
1c6e0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
1c6f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73  ** The first hos
1c700 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
1c710 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
1c720 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ot 0..**.** If t
1c730 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75  he value n is ou
1c740 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
1c750 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
1c760 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
1c770 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
1c780 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1c790 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1c7a0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
1c7b0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
1c7c0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
1c7d0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
1c7e0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
1c7f0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
1c800 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
1c810 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
1c820 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c830 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1c840 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1c850 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1c860 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1c870 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c880 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1c890 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1c8a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c8b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1c8c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1c8d0 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 63  ** [H13621].*/.c
1c8e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1c8f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c900 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
1c910 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
1c920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
1c930 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
1c940 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
1c950 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37  ame {H13640} <S7
1c960 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0300>.**.** Retu
1c970 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
1c980 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1c990 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
1c9a0 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76    The.** index v
1c9b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
1c9c0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
1c9d0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
1c9e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1c9f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1ca00 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1ca10 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69  )].  A zero.** i
1ca20 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
1ca30 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
1ca40 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54  ter is found.  T
1ca50 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1ca60 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
1ca70 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
1ca80 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
1ca90 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
1caa0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
1cab0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
1cac0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1cad0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1cae0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1caf0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1cb00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1cb10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1cb20 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1cb30 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1cb40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1cb50 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1cb60 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1cb70 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f  :.** [H13641].*/
1cb80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1cb90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1cba0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
1cbb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1cbc0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
1cbd0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
1cbe0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
1cbf0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1cc00 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30   {H13660} <S7030
1cc10 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72  0>.**.** Contrar
1cc20 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
1cc30 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
1cc40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
1cc50 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
1cc60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1cc70 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
1cc80 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
1cc90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1cca0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
1ccb0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
1ccc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
1ccd0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65  o NULL..**.** Re
1cce0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1ccf0 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73  H13661].*/.int s
1cd00 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
1cd10 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
1cd20 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1cd30 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
1cd40 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
1cd50 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30  sult Set {H13710
1cd60 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1cd70 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
1cd80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1cd90 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1cda0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
1cdb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1cdc0 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
1cdd0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
1cde0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
1cdf0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1ce00 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
1ce10 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
1ce20 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
1ce30 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  E])..**.** Requi
1ce40 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1ce50 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  711].*/.int sqli
1ce60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
1ce70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1ce80 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1ce90 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
1cea0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
1ceb0 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53   Set {H13720} <S
1cec0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
1ced0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1cee0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
1cef0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
1cf00 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
1cf10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1cf20 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1cf30 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73  tatement.  The s
1cf40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1cf50 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
1cf60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1cf70 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1cf80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1cf90 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
1cfa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1cfb0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
1cfc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
1cfd0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1cfe0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
1cff0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d000 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
1d010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1d020 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
1d030 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
1d040 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65  tatement. The se
1d050 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1d060 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
1d070 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66  number.  The lef
1d080 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
1d090 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
1d0a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1d0b0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
1d0c0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
1d0d0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
1d0e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
1d0f0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
1d100 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1d110 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
1d120 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
1d130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d140 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
1d150 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1d160 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
1d170 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71  umn..**.** If sq
1d180 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
1d190 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
1d1a0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
1d1b0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
1d1c0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
1d1d0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
1d1e0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
1d1f0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
1d200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
1d210 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1d220 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72   The name of a r
1d230 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
1d240 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1d250 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
1d260 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
1d270 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1d280 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
1d290 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
1d2a0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
1d2b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
1d2c0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
1d2d0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
1d2e0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
1d2f0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
1d300 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
1d310 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1d320 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31  .** [H13721] [H1
1d330 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b  3723] [H13724] [
1d340 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d  H13725] [H13726]
1d350 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e   [H13727].*/.con
1d360 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1d370 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1d380 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1d390 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1d3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d3b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1d3c0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1d3d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1d3e0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1d3f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1d400 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e  H13740} <S10700>
1d410 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d420 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
1d430 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
1d440 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
1d450 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
1d460 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
1d470 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
1d480 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1d490 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
1d4a0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
1d4b0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
1d4c0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
1d4d0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
1d4e0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
1d4f0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
1d500 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
1d510 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
1d520 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
1d530 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
1d540 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
1d550 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
1d560 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
1d570 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
1d580 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
1d590 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
1d5a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1d5b0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
1d5c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1d5d0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
1d5e0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
1d5f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1d600 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
1d610 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1d620 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
1d630 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
1d640 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
1d650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
1d660 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
1d670 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
1d680 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
1d690 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
1d6a0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
1d6b0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
1d6c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1d6d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
1d6e0 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
1d6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1d700 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
1d710 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1d720 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
1d730 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1d740 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
1d750 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
1d760 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
1d770 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1d780 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
1d790 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1d7a0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
1d7b0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
1d7c0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
1d7d0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
1d7e0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
1d7f0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
1d800 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1d810 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  .** NULL.  These
1d820 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
1d830 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
1d840 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
1d850 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
1d860 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
1d870 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
1d880 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1d890 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1d8a0 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20  e, table.** and 
1d8b0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
1d8c0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
1d8d0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
1d8e0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
1d8f0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
1d900 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
1d910 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
1d920 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
1d930 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
1d940 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
1d950 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
1d960 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
1d970 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
1d980 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
1d990 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
1d9a0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1d9b0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
1d9c0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
1d9d0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
1d9e0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
1d9f0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  efined..**.** {A
1da00 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
1da10 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
1da20 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
1da30 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1da40 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
1da50 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
1da60 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
1da70 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
1da80 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
1da90 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
1daa0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1dab0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1dac0 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34   [H13741] [H1374
1dad0 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33  2] [H13743] [H13
1dae0 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48  744] [H13745] [H
1daf0 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a  13746] [H13748].
1db00 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
1db10 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
1db20 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
1db30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1db40 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
1db50 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
1db60 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
1db70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
1db80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1db90 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
1dba0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
1dbb0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1dbc0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1dbd0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
1dbe0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1dbf0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1dc00 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1dc10 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1dc20 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1dc30 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1dc40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1dc50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
1dc60 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1dc70 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
1dc80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1dc90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1dca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1dcb0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
1dcc0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1dcd0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1dce0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1dcf0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1dd00 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1dd10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1dd20 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
1dd30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1dd40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1dd50 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
1dd60 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
1dd70 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36  ry Result {H1376
1dd80 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1dd90 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
1dda0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
1ddb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1ddc0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
1ddd0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
1dde0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
1ddf0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
1de00 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
1de10 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
1de20 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
1de30 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
1de40 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
1de50 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1de60 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
1de70 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
1de80 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
1de90 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
1dea0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
1deb0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
1dec0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
1ded0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1dee0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
1def0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1df00 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
1df10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1df20 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
1df30 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  coded. {END}.**.
1df40 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1df50 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
1df60 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
1df70 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
1df80 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
1df90 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
1dfa0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
1dfb0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
1dfc0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
1dfd0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
1dfe0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
1dff0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
1e000 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
1e010 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
1e020 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
1e030 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
1e040 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
1e050 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
1e060 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
1e070 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
1e080 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
1e090 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
1e0a0 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
1e0b0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
1e0c0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
1e0d0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
1e0e0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
1e0f0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
1e100 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
1e110 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
1e120 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
1e130 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
1e140 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
1e150 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
1e160 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
1e170 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
1e180 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
1e190 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
1e1a0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
1e1b0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
1e1c0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
1e1d0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
1e1e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1e1f0 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48 31  .** [H13761] [H1
1e200 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a 2a  3762] [H13763].*
1e210 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1e220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1e230 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
1e240 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1e250 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1e260 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
1e270 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1e280 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e290 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
1e2a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
1e2b0 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e  H13200} <S10000>
1e2c0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
1e2d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e2e0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
1e2f0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
1e300 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
1e310 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1e320 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e330 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
1e340 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
1e350 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
1e360 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e370 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1e380 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
1e390 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
1e3a0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
1e3b0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
1e3c0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
1e3d0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
1e3e0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
1e3f0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
1e400 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1e410 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
1e420 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
1e430 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
1e440 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
1e450 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
1e460 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
1e470 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e480 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1e490 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
1e4a0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
1e4b0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
1e4c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e4d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e4e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
1e4f0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
1e500 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
1e510 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
1e520 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
1e530 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
1e540 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
1e550 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
1e560 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
1e570 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
1e580 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1e590 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
1e5a0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
1e5b0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
1e5c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
1e5d0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
1e5e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
1e5f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
1e600 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
1e610 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1e620 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
1e630 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
1e640 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1e650 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
1e660 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
1e670 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
1e680 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
1e690 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
1e6a0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
1e6b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
1e6c0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
1e6d0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
1e6e0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
1e6f0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
1e700 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
1e710 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
1e720 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
1e730 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1e740 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
1e750 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
1e760 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
1e770 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
1e780 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
1e790 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
1e7a0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
1e7b0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
1e7c0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
1e7d0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
1e7e0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
1e7f0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
1e800 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
1e810 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
1e820 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
1e830 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
1e840 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
1e850 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
1e860 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
1e870 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
1e880 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
1e890 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
1e8a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1e8b0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
1e8c0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
1e8d0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
1e8e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
1e8f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
1e900 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1e910 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
1e920 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
1e930 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
1e940 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
1e950 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
1e960 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
1e970 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
1e980 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
1e990 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
1e9a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
1e9b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
1e9c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
1e9d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
1e9e0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
1e9f0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
1ea00 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
1ea10 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
1ea20 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
1ea30 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
1ea40 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
1ea50 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
1ea60 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
1ea70 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
1ea80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
1ea90 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
1eaa0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
1eab0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
1eac0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
1ead0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
1eae0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1eaf0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
1eb00 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1eb10 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
1eb20 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
1eb30 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
1eb40 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1eb50 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
1eb60 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
1eb70 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
1eb80 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
1eb90 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
1eba0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1ebb0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
1ebc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ebd0 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22  t].  In the "v2"
1ebe0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
1ebf0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
1ec00 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
1ec10 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
1ec20 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
1ec30 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
1ec40 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
1ec50 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
1ec60 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
1ec70 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
1ec80 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
1ec90 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
1eca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ecb0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
1ecc0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
1ecd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
1ece0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
1ecf0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
1ed00 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
1ed10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
1ed20 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
1ed30 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
1ed40 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
1ed50 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
1ed60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ed70 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
1ed80 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
1ed90 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
1eda0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
1edb0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
1edc0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
1edd0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
1ede0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
1edf0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
1ee00 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
1ee10 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1ee20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
1ee30 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
1ee40 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
1ee50 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
1ee60 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ee70 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
1ee80 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
1ee90 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
1eea0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1eeb0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
1eec0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
1eed0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
1eee0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
1eef0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
1ef00 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
1ef10 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
1ef20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
1ef30 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
1ef40 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
1ef50 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
1ef60 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
1ef70 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
1ef80 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
1ef90 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
1efa0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
1efb0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1efc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1efd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1efe0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
1eff0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
1f000 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
1f010 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
1f020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f030 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
1f040 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
1f050 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
1f060 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
1f070 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
1f080 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
1f090 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
1f0a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1f0b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
1f0c0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
1f0d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30  ments:.** [H1320
1f0e0 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35  2] [H15304] [H15
1f0f0 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48  306] [H15308] [H
1f100 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71  15310].*/.int sq
1f110 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
1f120 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
1f130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1f140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1f150 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48   a result set {H
1f160 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13770} <S10700>.
1f170 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68  **.** Returns th
1f180 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
1f190 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
1f1a0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
1f1b0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52  ult set..**.** R
1f1c0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1f1d0 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37 32  [H13771] [H13772
1f1e0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1f1f0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
1f200 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1f210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f220 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
1f230 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35  atatypes {H10265
1f240 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32  } <S10110><S1012
1f250 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1f260 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
1f270 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79  * {H10266} Every
1f280 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
1f290 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
1f2a0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
1f2b0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
1f2c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
1f2d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1f2e0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
1f2f0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
1f300 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
1f310 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
1f320 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
1f330 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
1f340 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
1f350 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
1f360 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
1f370 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
1f380 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
1f390 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
1f3a0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
1f3b0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
1f3c0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
1f3d0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
1f3e0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
1f3f0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
1f400 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
1f410 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
1f420 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
1f430 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
1f440 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
1f450 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
1f460 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
1f470 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
1f480 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
1f490 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
1f4a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
1f4b0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1f4c0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
1f4d0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
1f4e0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
1f4f0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
1f500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
1f510 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
1f520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
1f530 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
1f540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
1f550 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
1f560 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20   Query {H13800} 
1f570 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
1f580 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
1f590 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
1f5a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1f5b0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
1f5c0 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
1f5d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
1f5e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1f5f0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1f600 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
1f610 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
1f620 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
1f630 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
1f640 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73  y.  In every cas
1f650 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
1f660 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1f670 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
1f680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f690 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
1f6a0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
1f6b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
1f6c0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
1f6d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1f6e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f6f0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
1f700 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
1f710 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1f720 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1f730 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
1f740 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
1f750 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
1f760 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
1f770 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
1f780 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1f790 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
1f7a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
1f7b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1f7c0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
1f7d0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
1f7e0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
1f7f0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
1f800 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1f810 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
1f820 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
1f830 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
1f840 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
1f850 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
1f860 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
1f870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f880 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
1f890 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
1f8a0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
1f8b0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
1f8c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1f8d0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
1f8e0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
1f8f0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
1f900 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1f910 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
1f920 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f930 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1f940 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1f950 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
1f960 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
1f970 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
1f980 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1f990 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
1f9a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1f9b0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
1f9c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
1f9d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1f9e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
1f9f0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
1fa00 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
1fa10 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
1fa20 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
1fa30 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
1fa40 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
1fa50 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
1fa60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1fa70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
1fa80 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
1fa90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
1faa0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
1fab0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
1fac0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
1fad0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
1fae0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
1faf0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
1fb00 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
1fb10 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
1fb20 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
1fb30 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
1fb40 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
1fb50 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
1fb60 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
1fb70 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1fb80 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
1fb90 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
1fba0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
1fbb0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
1fbc0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
1fbd0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
1fbe0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
1fbf0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
1fc00 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
1fc10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1fc20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
1fc30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1fc40 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
1fc50 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
1fc60 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
1fc70 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
1fc80 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
1fc90 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
1fca0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
1fcb0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
1fcc0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
1fcd0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
1fce0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
1fcf0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
1fd00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1fd10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1fd20 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
1fd30 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
1fd40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
1fd50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
1fd60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
1fd70 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
1fd80 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
1fd90 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
1fda0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
1fdb0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1fdc0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
1fdd0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
1fde0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
1fdf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
1fe00 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
1fe10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
1fe20 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
1fe30 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
1fe40 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
1fe50 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
1fe60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
1fe70 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
1fe80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fe90 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1fea0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1feb0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
1fec0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
1fed0 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
1fee0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1fef0 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
1ff00 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
1ff10 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
1ff20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1ff30 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1ff40 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
1ff50 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
1ff60 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
1ff70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1ff80 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
1ff90 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
1ffa0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
1ffb0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
1ffc0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
1ffd0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
1ffe0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
1fff0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
20000 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
20010 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
20020 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
20030 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
20040 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
20050 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
20060 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
20070 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
20080 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
20090 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
200a0 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
200b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
200c0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
200d0 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  F-8..** The zero
200e0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
200f0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
20100 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
20110 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
20120 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
20130 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
20140 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
20150 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20160 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
20170 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
20180 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20190 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
201a0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
201b0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
201c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
201d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
201e0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
201f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20200 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
20210 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
20220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
20230 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
20240 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
20250 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
20260 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
20270 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
20280 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
20290 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
202a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
202b0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
202c0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
202d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
202e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
202f0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
20300 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
20310 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
20320 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
20330 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
20340 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
20350 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
20360 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
20370 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
20380 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
20390 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
203a0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
203b0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
203c0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
203d0 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
203e0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
203f0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
20400 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
20410 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
20420 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
20430 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
20440 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
20450 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
20460 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
20470 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
20480 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
20490 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
204a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
204b0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
204c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
204d0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
204e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
204f0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
20500 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
20510 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
20520 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
20530 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
20540 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
20550 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
20560 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
20570 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
20580 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
20590 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
205a0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
205b0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
205c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
205d0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
205e0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
205f0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
20600 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
20610 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
20620 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
20630 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
20640 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
20650 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
20660 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
20670 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
20680 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
20690 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
206a0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
206b0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
206c0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
206d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
206e0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
206f0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
20700 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
20710 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
20720 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
20730 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
20740 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
20750 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
20760 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
20770 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
20780 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
20790 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
207a0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
207b0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
207c0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
207d0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
207e0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
207f0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
20800 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
20810 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
20820 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
20830 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
20840 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
20850 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
20860 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
20870 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
20880 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
20890 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
208a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
208b0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
208c0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
208d0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
208e0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
208f0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
20900 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
20910 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
20920 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
20930 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
20940 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
20950 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
20960 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
20970 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
20980 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
20990 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
209a0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
209b0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
209c0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
209d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
209e0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
209f0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
20a00 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
20a10 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
20a20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
20a30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
20a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20a50 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
20a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20a70 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
20a80 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
20a90 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
20aa0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
20ab0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
20ac0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
20ad0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
20ae0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20af0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
20b00 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
20b10 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
20b20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
20b30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
20b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
20b50 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
20b60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
20b70 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
20b80 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
20b90 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
20ba0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
20bb0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
20bc0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
20bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
20be0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
20bf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
20c00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
20c10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
20c20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
20c30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
20c40 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
20c50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
20c60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
20c70 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
20c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20c90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
20ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
20cb0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
20cc0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
20cd0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
20ce0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
20cf0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
20d00 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
20d10 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
20d20 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
20d30 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
20d40 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
20d50 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
20d60 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
20d70 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
20d80 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
20d90 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
20da0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
20db0 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
20dc0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
20dd0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
20de0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
20df0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
20e00 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
20e10 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
20e20 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
20e30 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
20e40 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
20e50 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
20e60 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
20e70 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
20e80 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
20e90 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
20ea0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
20eb0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
20ec0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
20ed0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
20ee0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
20ef0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
20f00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
20f10 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
20f20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
20f30 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
20f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
20f50 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
20f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20f70 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
20f80 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
20f90 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
20fa0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
20fb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
20fc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
20fd0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
20fe0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
20ff0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
21000 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
21010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
21020 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
21030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
21040 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
21050 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
21060 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
21070 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
21080 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
21090 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
210a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
210b0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
210c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
210d0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
210e0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
210f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21100 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
21110 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
21120 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
21130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21140 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
21150 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
21160 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21170 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
21180 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
21190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
211a0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
211b0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
211c0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
211d0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
211e0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
211f0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
21200 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
21210 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
21220 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
21230 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
21240 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
21250 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
21260 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
21270 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
21280 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
21290 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
212a0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
212b0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
212c0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
212d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
212e0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
212f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
21300 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
21310 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
21320 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
21330 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
21340 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
21350 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
21360 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
21370 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
21380 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
21390 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
213a0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
213b0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
213c0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
213d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
213e0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
213f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
21400 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
21410 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
21420 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
21430 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
21440 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  EM]..**.** Requi
21450 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
21460 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48  803] [H13806] [H
21470 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20  13809] [H13812] 
21480 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38  [H13815] [H13818
21490 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38  ] [H13821] [H138
214a0 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20  24].** [H13827] 
214b0 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73  [H13830].*/.cons
214c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
214d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
214e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
214f0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
21500 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
21510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21520 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
21530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21540 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
21550 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
21560 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
21570 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
21580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21590 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
215a0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
215b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
215c0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
215d0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
215e0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
215f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21600 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
21610 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
21620 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
21630 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21640 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
21650 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21660 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
21670 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
21680 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
21690 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
216a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
216b0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
216c0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
216d0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
216e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
216f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21700 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
21710 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
21720 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20  Object {H13300} 
21730 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e  <S70300><S30100>
21740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21750 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
21760 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
21770 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
21780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21790 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61  ]..** If the sta
217a0 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75  tement was execu
217b0 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
217c0 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
217d0 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a   at all, then.**
217e0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
217f0 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75  turned. If execu
21800 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
21810 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
21820 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
21830 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
21840 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
21850 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
21860 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
21870 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
21880 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
21890 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
218a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
218b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
218c0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
218d0 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a  chine has not.**
218e0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
218f0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
21900 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
21910 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
21920 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
21930 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73  n error or an [s
21940 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
21950 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a   | interrupt]..*
21960 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
21970 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
21980 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
21990 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65  sactions cancele
219a0 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  d,.** depending 
219b0 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
219c0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  nces, and the.**
219d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65   [error code] re
219e0 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b  turned will be [
219f0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
21a00 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
21a10 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b  s:.** [H11302] [
21a20 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H11304].*/.int s
21a30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
21a50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
21a60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
21a70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
21a80 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30  t Object {H13330
21a90 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
21aa0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
21ab0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
21ac0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
21ad0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21ae0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
21af0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
21b00 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
21b10 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
21b20 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
21b30 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
21b40 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
21b50 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
21b60 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
21b70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21b80 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
21b90 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
21ba0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
21bb0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
21bc0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
21bd0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
21be0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
21bf0 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  H11332} The [sql
21c00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
21c10 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
21c20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21c30 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
21c40 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
21c50 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
21c60 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
21c70 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74  ** {H11334} If t
21c80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
21c90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21ca0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
21cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
21cc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21cd0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
21ce0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
21cf0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
21d00 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
21d10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
21d20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
21d30 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
21d40 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
21d50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
21d60 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
21d70 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
21d80 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68  * {H11336} If th
21d90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
21da0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21db0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
21dc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
21dd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21de0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
21df0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
21e00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21e10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
21e20 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
21e30 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
21e40 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54  **.** {H11338} T
21e50 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
21e60 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
21e70 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
21e80 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
21e90 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
21ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21eb0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
21ec0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21ed0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
21ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
21ef0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
21f00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
21f10 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
21f20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
21f30 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20  ctions {H16100} 
21f40 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
21f50 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
21f60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
21f70 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
21f80 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
21f90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
21fa0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
21fb0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
21fc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
21fd0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
21fe0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
21ff0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
22000 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
22010 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
22020 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
22030 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
22040 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
22050 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
22060 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
22070 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
22080 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
22090 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
220a0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
220b0 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
220c0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
220d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
220e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
220f0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
22100 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
22110 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
22120 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
22130 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
22140 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
22150 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
22160 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
22170 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
22180 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
221a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
221b0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
221c0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
221d0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
221e0 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65  ngle program use
221f0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
22200 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
22210 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c  ection internall
22220 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63  y, then SQL func
22230 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
22240 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
22250 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61   to.** each data
22260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
22270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
22280 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
22290 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
222a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
222b0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
222c0 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  redefined.  The 
222d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
222e0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
222f0 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
22300 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
22310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
22320 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
22330 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
22340 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
22350 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
22360 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
22370 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
22380 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
22390 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
223a0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
223b0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
223c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
223d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
223e0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
223f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
22400 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
22410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
22420 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
22430 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
22440 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
22450 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
22460 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
22470 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
22480 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
22490 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
224a0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
224b0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
224c0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
224d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
224e0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
224f0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
22500 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
22510 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
22520 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
22530 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
22540 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
22550 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
22560 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
22570 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
22580 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
22590 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
225a0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
225b0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
225c0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
225d0 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
225e0 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
225f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
22600 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
22610 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
22620 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
22630 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
22640 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
22650 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
22660 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
22670 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
22680 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
22690 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
226a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
226b0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
226c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
226d0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
226e0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
226f0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
22700 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
22710 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
22720 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
22730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
22740 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
22750 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
22760 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
22770 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
22780 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
22790 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
227a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
227b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
227c0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
227d0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
227e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
227f0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
22800 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
22810 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
22820 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
22830 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
22840 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
22850 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
22860 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
22870 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
22880 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
22890 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
228a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
228b0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
228c0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
228d0 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
228e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
228f0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
22900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
22910 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
22920 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
22930 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
22940 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
22950 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
22960 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
22970 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
22980 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
22990 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
229a0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
229b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
229c0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
229d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
229e0 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
229f0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
22a00 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
22a10 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
22a20 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
22a30 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
22a40 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
22a50 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
22a60 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
22a70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
22a80 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
22a90 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
22aa0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
22ab0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
22ac0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
22ad0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
22ae0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
22af0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
22b00 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
22b10 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
22b20 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
22b30 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
22b40 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
22b50 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
22b60 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75  n is used.  A fu
22b70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
22b80 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
22b90 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
22ba0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
22bb0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
22bc0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
22bd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
22be0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
22bf0 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f  nArg.  A functio
22c00 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
22c10 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
22c20 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
22c30 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
22c40 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
22c50 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
22c60 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
22c70 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
22c80 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
22c90 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
22ca0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
22cb0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
22cc0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
22cd0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
22ce0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
22cf0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
22d00 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
22d10 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
22d20 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
22d30 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42  d UTF16..**.** B
22d40 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
22d50 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
22d60 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
22d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
22d80 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  unctions..** The
22d90 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
22da0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
22db0 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
22dc0 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
22dd0 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
22de0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
22df0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
22e00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
22e10 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
22e20 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70  ** Subsequent ap
22e30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
22e40 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74  d functions of t
22e50 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c  he same name onl
22e60 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70  y override .** p
22e70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  rior application
22e80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
22e90 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65  ns that are an e
22ea0 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74  xact match for t
22eb0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
22ec0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70  parameters and p
22ed0 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e  referred encodin
22ee0 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c  g..**.** An appl
22ef0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
22f10 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
22f20 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
22f30 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
22f40 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
22f50 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
22f60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22f70 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
22f80 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
22f90 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
22fa0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
22fb0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
22fc0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
22fd0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
22fe0 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 31  * [H16103] [H161
22ff0 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 31  06] [H16109] [H1
23000 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b  6112] [H16118] [
23010 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 34 5d  H16121] [H16124]
23020 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31   [H16127].** [H1
23030 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b  6130] [H16133] [
23040 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39 5d  H16136] [H16139]
23050 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74   [H16142].*/.int
23060 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
23070 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
23080 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
23090 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
230a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
230b0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
230c0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
230d0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
230e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
230f0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
23100 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
23110 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
23120 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
23130 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
23140 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
23150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
23160 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
23170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
23180 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
23190 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
231a0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
231b0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
231c0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
231d0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
231e0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
231f0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
23200 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
23210 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
23220 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
23230 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
23240 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
23250 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
23260 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
23270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
23280 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
23290 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
232a0 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
232b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
232c0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
232d0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
232e0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
232f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
23300 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
23310 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
23320 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
23330 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
23340 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
23350 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
23360 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
23370 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
23380 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
23390 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
233a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
233b0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
233c0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
233d0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
233e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
233f0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
23400 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
23410 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
23420 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
23430 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
23440 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
23450 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
23460 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
23470 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
23480 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
23490 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
234a0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
234b0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
234c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
234d0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
234e0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
234f0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
23500 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
23510 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
23520 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
23530 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
23540 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
23550 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
23560 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
23570 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
23580 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
23590 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
235a0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
235b0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
235c0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
235d0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
235e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
235f0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
23600 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
23610 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
23620 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23630 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
23640 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
23650 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
23660 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
23670 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
23680 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
23690 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
236a0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
236b0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
236c0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
236d0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
236e0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
236f0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
23700 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
23710 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
23730 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
23740 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
23750 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
23760 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
23770 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
23780 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
23790 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
237a0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
237b0 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
237c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
237d0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
237e0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
237f0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
23800 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
23810 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
23820 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
23830 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
23840 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
23850 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
23860 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
23870 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
23880 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
23890 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
238a0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
238b0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
238c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
238d0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
238e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
238f0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
23900 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
23910 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
23920 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
23930 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
23940 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
23950 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
23960 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
23970 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
23980 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
23990 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
239a0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
239b0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
239c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
239d0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
239e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
239f0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
23a00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
23a10 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
23a20 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
23a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
23a40 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
23a50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
23a60 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
23a70 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
23a80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
23a90 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
23aa0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
23ab0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
23ac0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23ad0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
23ae0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
23af0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
23b00 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
23b10 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
23b20 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
23b30 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
23b40 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
23b50 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
23b60 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
23b70 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
23b80 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
23b90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
23ba0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
23bb0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
23bc0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
23bd0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
23be0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
23bf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23c00 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
23c10 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
23c20 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
23c30 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
23c40 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
23c50 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
23c60 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
23c70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
23c80 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
23c90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
23ca0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
23cb0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
23cc0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
23cd0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
23ce0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
23cf0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
23d00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
23d10 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
23d20 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
23d30 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
23d40 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
23d50 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
23d60 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
23d70 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
23d80 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
23d90 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
23da0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
23db0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
23dc0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
23dd0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
23de0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
23df0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
23e00 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
23e10 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
23e20 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
23e30 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
23e40 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
23e50 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
23e60 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
23e70 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
23e80 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
23e90 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
23ea0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
23eb0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
23ec0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
23ed0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
23ee0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
23ef0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
23f00 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
23f10 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
23f20 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
23f30 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
23f40 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
23f50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
23f60 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
23f70 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
23f80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
23f90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
23fa0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
23fb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
23fc0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
23fd0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
23fe0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
23ff0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
24000 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
24010 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
24020 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
24030 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
24040 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
24050 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
24060 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
24070 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
24080 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
24090 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33  ents:.** [H15103
240a0 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35 31  ] [H15106] [H151
240b0 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48 31  09] [H15112] [H1
240c0 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b  5115] [H15118] [
240d0 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34 5d  H15121] [H15124]
240e0 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48 31  .** [H15127] [H1
240f0 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b  5130] [H15133] [
24100 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74  H15136].*/.const
24110 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
24120 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
24130 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
24140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
24150 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
24160 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24170 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
24180 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
24190 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
241a0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
241b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
241c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
241d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
241e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
241f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
24200 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
24210 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
24220 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
24230 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
24240 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
24250 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
24260 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
24270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24280 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
242a0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
242b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
242c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
242d0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
242e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
242f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
24300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
24320 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
24330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24350 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
24360 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
24370 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32  ext {H16210} <S2
24380 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
24390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
243a0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
243b0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
243c0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
243d0 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
243e0 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
243f0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
24400 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74  *.** The first t
24410 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
24420 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
24430 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  t() routine is c
24440 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70  alled for a.** p
24450 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
24460 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f  ate, SQLite allo
24470 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20  cates nBytes of 
24480 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
24490 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72  ut that.** memor
244a0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
244b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
244c0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
244d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
244e0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
244f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
24500 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
24510 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
24520 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73   index,.** the s
24530 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
24540 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c  turned. The impl
24550 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
24560 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20  e aggregate can 
24570 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  use.** the retur
24580 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63  ned buffer to ac
24590 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a  cumulate data..*
245a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f  *.** SQLite auto
245b0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
245c0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75  the allocated bu
245d0 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67  ffer when the ag
245e0 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79  gregate.** query
245f0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
24600 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
24610 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
24620 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
24630 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
24640 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
24650 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
24660 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
24670 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
24680 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
24690 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
246a0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
246b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
246c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
246d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
246e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
246f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
24700 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
24710 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
24720 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  g..**.** Require
24730 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31  ments:.** [H1621
24740 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31 36  1] [H16213] [H16
24750 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f  215] [H16217].*/
24760 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
24770 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
24780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24790 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
247a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
247b0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
247c0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30  unctions {H16240
247d0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
247e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65   The sqlite3_use
247f0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
24800 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
24810 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
24820 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
24830 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
24840 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
24850 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
24860 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
24870 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
24880 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
24890 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
248a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
248b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
248c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
248d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
248e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e  ed function. {EN
248f0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  D}.**.** This ro
24900 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
24910 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
24920 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
24930 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
24940 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
24950 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
24960 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  g..**.** Require
24970 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34  ments:.** [H1624
24980 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  3].*/.void *sqli
24990 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
249a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
249b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
249c0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
249d0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
249e0 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36  ons {H16250} <S6
249f0 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a  0600><S20200>.**
24a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24a10 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
24a20 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
24a30 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
24a40 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
24a50 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
24a60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
24a70 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
24a80 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
24a90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24aa0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
24ab0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24ac0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
24ad0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
24ae0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
24af0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
24b00 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
24b10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  on..**.** Requir
24b20 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
24b30 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  53].*/.sqlite3 *
24b40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
24b50 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
24b60 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
24b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
24b80 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
24b90 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c   Data {H16270} <
24ba0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
24bb0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
24bc0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
24bd0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
24be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
24bf0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
24c00 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
24c10 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
24c20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
24c30 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
24c40 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
24c50 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
24c60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
24c70 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
24c80 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
24c90 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
24ca0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
24cb0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
24cc0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
24cd0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
24ce0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
24cf0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
24d00 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
24d10 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
24d20 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
24d30 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
24d40 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
24d50 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
24d60 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
24d70 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24d80 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
24d90 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
24da0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
24db0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
24dc0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
24dd0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
24de0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
24df0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
24e00 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
24e10 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
24e20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
24e30 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
24e40 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
24e50 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
24e60 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
24e70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24e80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
24e90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24ea0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
24eb0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
24ec0 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
24ed0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
24ee0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
24ef0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
24f00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
24f10 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
24f20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
24f30 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61  tion. If no meta
24f40 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
24f50 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
24f60 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
24f70 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
24f80 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
24f90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
24fa0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
24fb0 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
24fc0 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
24fd0 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
24fe0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
24ff0 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
25000 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
25010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25020 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
25030 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
25040 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
25050 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
25060 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
25070 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
25080 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
25090 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
250a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
250b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
250c0 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
250d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
250e0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
250f0 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
25100 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
25110 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
25120 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20  royed..** If it 
25130 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
25140 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
25150 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
25160 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
25170 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
25180 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25190 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
251a0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
251b0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
251c0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
251d0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
251e0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
251f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
25200 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
25210 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
25220 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
25230 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
25240 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
25250 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
25260 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
25270 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
25280 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
25290 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72  .  The only guar
252a0 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
252b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
252c0 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
252d0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
252e0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
252f0 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65  *.** In practice
25300 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
25310 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
25320 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
25330 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
25340 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
25350 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
25360 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
25370 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
25380 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
25390 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
253a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
253b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
253c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
253d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
253e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
253f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
25400 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
25410 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32 37   [H16272] [H1627
25420 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31 36  4] [H16276] [H16
25430 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48  277] [H16278] [H
25440 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  16279].*/.void *
25450 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25460 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
25470 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
25480 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
25490 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
254a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
254b0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
254c0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
254d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
254e0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
254f0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
25500 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38   Behavior {H1028
25510 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S30100>.**.*
25520 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
25530 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
25540 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
25550 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
25560 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
25570 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
25580 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
25590 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
255a0 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
255b0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
255c0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
255d0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
255e0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
255f0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
25600 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
25610 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
25620 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
25630 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
25640 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
25650 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
25660 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
25670 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
25680 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
25690 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
256a0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
256b0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
256c0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
256d0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
256e0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
256f0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
25700 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
25710 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
25720 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
25730 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
25740 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
25750 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
25760 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
25770 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
25780 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
25790 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
257a0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
257b0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
257c0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
257d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
257e0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
257f0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
25800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
25810 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
25820 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
25830 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53  tion {H16400} <S
25840 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
25850 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
25860 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
25870 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
25880 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
25890 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
258a0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
258b0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
258c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
258d0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
258e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
258f0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
25900 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
25910 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
25920 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
25930 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
25940 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
25950 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
25960 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
25970 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
25980 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
25990 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
259a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
259b0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
259c0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
259d0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
259e0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
259f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25a00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
25a10 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
25a20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
25a30 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
25a40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
25a50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
25a60 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
25a70 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
25a80 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
25a90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
25aa0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
25ab0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
25ac0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
25ad0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25ae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25af0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
25b00 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
25b10 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
25b20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
25b30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
25b40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
25b50 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
25b60 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
25b70 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
25b80 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
25b90 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25ba0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
25bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25bc0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
25bd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
25be0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
25bf0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
25c00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
25c10 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
25c20 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
25c30 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
25c40 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
25c50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
25c60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
25c70 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
25c80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
25c90 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
25ca0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
25cb0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
25cc0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
25cd0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
25ce0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
25cf0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
25d00 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
25d10 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
25d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
25d30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
25d40 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
25d50 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
25d60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
25d70 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
25d80 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
25d90 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
25da0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
25db0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
25dc0 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
25dd0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
25de0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
25df0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
25e00 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
25e10 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
25e20 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
25e30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
25e40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
25e50 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
25e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
25e70 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
25e80 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
25e90 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
25ea0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
25eb0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
25ec0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
25ed0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
25ee0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
25ef0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25f00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
25f10 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
25f20 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
25f30 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
25f40 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
25f50 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
25f60 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
25f70 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
25f80 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
25f90 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
25fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25fb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
25fc0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
25fd0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
25fe0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
25ff0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
26000 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
26010 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
26020 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
26030 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
26040 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
26050 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
26060 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
26070 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
26080 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
26090 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
260a0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
260b0 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
260c0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
260d0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
260e0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
260f0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
26100 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
26110 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
26120 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
26130 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
26140 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
26150 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
26160 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
26170 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
26180 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
26190 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
261a0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
261b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
261c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
261d0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
261e0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
261f0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
26200 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
26210 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
26220 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
26230 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
26240 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26250 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
26260 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
26270 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
26280 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
26290 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
262a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
262b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
262c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
262d0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
262e0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
262f0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
26300 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26310 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26320 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
26330 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
26340 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
26350 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
26360 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26370 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
26380 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
26390 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
263a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
263b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
263c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
263d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
263e0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
263f0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
26400 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
26410 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26420 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
26430 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
26440 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
26450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
26460 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
26470 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
26480 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26490 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
264a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
264b0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
264c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
264d0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
264e0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
264f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
26500 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
26510 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
26520 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26530 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
26540 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
26550 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
26560 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
26570 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
26580 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
26590 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
265a0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
265b0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
265c0 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
265d0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
265e0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
265f0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
26600 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
26610 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
26620 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
26630 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
26640 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
26650 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
26660 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
26670 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
26680 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
26690 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
266a0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
266b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
266c0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
266d0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
266e0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
266f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
26700 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
26710 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
26720 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
26730 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
26740 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
26750 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
26760 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
26770 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
26780 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
26790 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
267a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
267b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
267c0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
267d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
267e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
267f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
26800 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
26810 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
26820 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
26830 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
26840 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
26850 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
26860 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
26870 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
26880 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
26890 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
268a0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
268b0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
268c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
268d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
268e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
268f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
26900 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
26910 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
26920 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
26930 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
26940 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
26950 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
26960 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
26970 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
26980 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
26990 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
269a0 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
269b0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
269c0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
269d0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
269e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
269f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26a00 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
26a10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
26a20 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
26a30 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
26a40 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
26a50 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
26a60 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
26a70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
26a80 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
26a90 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
26aa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
26ab0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
26ac0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
26ad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
26ae0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
26af0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
26b00 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
26b10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26b20 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
26b30 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
26b40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26b50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
26b60 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
26b70 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
26b80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
26b90 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
26ba0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
26bb0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
26bc0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
26bd0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
26be0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
26bf0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
26c00 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
26c10 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
26c20 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
26c30 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
26c40 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
26c50 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
26c60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26c70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
26c80 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
26c90 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
26ca0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26cb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
26cc0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
26cd0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
26ce0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26cf0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
26d00 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
26d10 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
26d20 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26d30 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
26d40 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
26d50 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
26d60 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
26d70 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
26d80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26d90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
26da0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
26db0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
26dc0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
26dd0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
26de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
26df0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34  ements:.** [H164
26e00 30 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48 31  03] [H16406] [H1
26e10 36 34 30 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b  6409] [H16412] [
26e20 48 31 36 34 31 35 5d 20 5b 48 31 36 34 31 38 5d  H16415] [H16418]
26e30 20 5b 48 31 36 34 32 31 5d 20 5b 48 31 36 34 32   [H16421] [H1642
26e40 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b  4].** [H16427] [
26e50 48 31 36 34 33 30 5d 20 5b 48 31 36 34 33 33 5d  H16430] [H16433]
26e60 20 5b 48 31 36 34 33 36 5d 20 5b 48 31 36 34 33   [H16436] [H1643
26e70 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48 31 36  9] [H16442] [H16
26e80 34 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a  445] [H16448].**
26e90 20 5b 48 31 36 34 35 31 5d 20 5b 48 31 36 34 35   [H16451] [H1645
26ea0 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48 31 36  4] [H16457] [H16
26eb0 34 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f  460] [H16463].*/
26ec0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
26ed0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
26ee0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
26ef0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
26f00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
26f10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
26f20 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
26f30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
26f40 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
26f50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
26f60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
26f70 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
26f80 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
26f90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
26fa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26fb0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
26fc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
26fd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
26fe0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
26ff0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
27000 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27010 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
27020 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
27030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27040 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
27050 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
27060 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27070 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
27080 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
27090 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
270a0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
270b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
270c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
270d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
270e0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
270f0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
27100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27110 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
27120 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
27130 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
27140 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
27150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
27160 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
27170 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
27180 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
27190 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
271a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
271b0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
271c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
271d0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
271e0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
271f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27200 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
27210 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27220 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
27230 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
27250 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
27260 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
27270 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
27280 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
27290 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
272a0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
272b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
272c0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
272d0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b  ting Sequences {
272e0 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16600} <S20300>
272f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
27300 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
27310 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
27320 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
27330 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  o the.** [databa
27340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
27350 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
27360 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
27370 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
27380 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74  f the new collat
27390 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
273a0 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55  specified as a U
273b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
273c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
273d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
273e0 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
273f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
27400 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
27410 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
27420 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27430 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20  ion16(). In all 
27440 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
27450 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
27460 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
27470 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
27480 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
27490 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
274a0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
274b0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
274c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
274d0 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  6LE] or [SQLITE_
274e0 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
274f0 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
27500 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
27510 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
27520 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
27530 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
27540 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
27550 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
27560 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72  ittle-endian, or
27570 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
27580 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
27590 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  . The.** third a
275a0 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
275b0 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
275c0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20  F16_ALIGNED] to 
275d0 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a  indicate that.**
275e0 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70   the routine exp
275f0 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
27600 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69   16-bit word ali
27610 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  gned strings.** 
27620 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  of UTF-16 in the
27630 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27640 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
27650 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
27660 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
27670 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
27680 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
27690 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
276a0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
276b0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
276c0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
276d0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
276e0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
276f0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
27700 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
27710 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
27720 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
27730 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70  application supp
27740 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  lied function is
27750 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20   invoked, it is 
27760 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73  passed.** as its
27770 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27780 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
27790 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74  oid* passed as t
277a0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
277b0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
277c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
277d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
277e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
277f0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  6()..**.** The r
27800 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
27810 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
27820 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
27830 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
27840 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
27850 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
27860 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
27870 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
27880 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
27890 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
278a0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
278b0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
278c0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
278d0 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
278e0 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20  istered. {END}  
278f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27900 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
27910 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  n routine should
27920 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74  .** return negat
27930 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
27940 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72  itive if the fir
27950 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
27960 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c  s than,.** equal
27970 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
27980 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20  than the second 
27990 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
279a0 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
279b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
279c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
279d0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
279e0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
279f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
27a00 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
27a10 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
27a20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
27a30 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
27a40 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
27a50 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
27a60 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
27a70 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
27a80 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
27a90 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
27aa0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
27ab0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27ac0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
27ad0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
27ae0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27af0 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74  _v2()..** Collat
27b00 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
27b10 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
27b20 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
27b30 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
27b40 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  e.** collation c
27b50 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
27b60 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64  s or when the [d
27b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27b80 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a  on] is closed.**
27b90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27ba0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
27bb0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
27bc0 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30   [H16603] [H1660
27bd0 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36  4] [H16606] [H16
27be0 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48  609] [H16612] [H
27bf0 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20  16615] [H16618] 
27c00 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36  [H16621].** [H16
27c10 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48  624] [H16627] [H
27c20 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16630].*/.int sq
27c30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27c40 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
27c50 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
27c60 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
27c70 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
27c80 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
27c90 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
27ca0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
27cb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
27cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
27cd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27ce0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
27cf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
27d00 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
27d10 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
27d20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
27d30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27d40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27d50 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
27d60 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
27d70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
27d80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
27d90 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
27da0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
27db0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
27dc0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
27dd0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
27de0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
27df0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
27e00 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
27e10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
27e20 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
27e30 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
27e40 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
27e50 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
27e60 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
27e70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
27e80 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
27e90 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
27ea0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
27eb0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
27ec0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
27ed0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
27ee0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27ef0 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
27f00 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
27f10 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
27f20 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
27f30 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
27f40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
27f50 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
27f60 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
27f70 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
27f80 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
27f90 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
27fa0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
27fb0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
27fc0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
27fd0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
27fe0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
27ff0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
28000 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
28010 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
28020 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
28030 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
28040 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
28050 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
28060 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
28070 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
28080 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
28090 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
280a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
280b0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
280c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
280d0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
280e0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
280f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28100 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28110 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
28120 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28130 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
28140 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
28150 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
28160 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
28170 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28180 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
28190 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
281a0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
281b0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
281c0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
281d0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
281e0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
281f0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
28200 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
28210 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
28220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28230 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28240 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
28250 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
28260 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
28270 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
28280 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
28290 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
282a0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
282b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
282c0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
282d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
282e0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
282f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28300 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
28310 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
28320 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d  nts:.** [H16702]
28330 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30   [H16704] [H1670
28340 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  6].*/.int sqlite
28350 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28360 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
28370 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
28380 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
28390 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
283a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
283b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
283c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
283d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
283e0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
283f0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
28400 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
28410 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
28420 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
28430 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
28440 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
28450 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
28460 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
28470 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
28480 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
28490 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
284a0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
284b0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
284c0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
284d0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
284e0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
284f0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
28500 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28510 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
28520 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
28530 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
28540 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
28550 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
28560 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
28570 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
28580 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
28590 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
285a0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
285b0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
285c0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
285d0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
285e0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
285f0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
28600 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
28610 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
28620 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
28630 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
28640 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
28650 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
28660 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
28670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28680 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
28690 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
286a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
286b0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
286c0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
286d0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
286e0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
286f0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
28700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
28710 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
28720 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
28730 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30  {H10530} <S40410
28740 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
28750 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
28760 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
28770 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
28780 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
28790 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
287a0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
287b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
287c0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
287d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
287e0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
287f0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
28800 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
28810 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
28820 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
28830 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
28840 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
28850 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
28860 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
28870 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
28880 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
28890 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
288a0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
288b0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
288c0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
288d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
288e0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
288f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
28900 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
28910 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
28920 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
28930 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
28940 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ject..**.** Requ
28950 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33  irements: [H1053
28960 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69  3] [H10536].*/.i
28970 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
28980 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
28990 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
289a0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
289b0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
289c0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
289d0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
289e0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
289f0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
28a00 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
28a10 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
28a20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
28a30 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
28a40 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
28a50 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
28a60 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
28a70 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
28a80 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
28a90 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
28aa0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
28ab0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
28ac0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
28ad0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
28ae0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
28af0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
28b00 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
28b10 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
28b20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
28b30 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
28b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28b50 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
28b60 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
28b70 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
28b80 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
28b90 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
28ba0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
28bb0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
28bc0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
28bd0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
28be0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
28bf0 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
28c00 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
28c10 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
28c20 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
28c30 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
28c40 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
28c50 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
28c60 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
28c70 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30  de {H12930} <S60
28c80 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
28c90 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
28ca0 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
28cb0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
28cc0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
28cd0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
28ce0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
28cf0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
28d00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
28d10 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
28d20 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
28d30 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
28d40 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
28d50 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
28d60 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
28d70 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
28d80 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
28d90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
28da0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
28db0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
28dc0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
28dd0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
28de0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
28df0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
28e00 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
28e10 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
28e20 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
28e30 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
28e40 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
28e50 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
28e60 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
28e70 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
28e80 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
28e90 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
28ea0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
28eb0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
28ec0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
28ed0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
28ee0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
28ef0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
28f00 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
28f10 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
28f20 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
28f30 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
28f40 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
28f50 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
28f60 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
28f70 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
28f80 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
28f90 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
28fa0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
28fb0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
28fc0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
28fd0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
28fe0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
28ff0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  efined..**.** Re
29000 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 32  quirements: [H12
29010 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b 48  931] [H12932] [H
29020 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d 0a  12933] [H12934].
29030 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
29040 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
29050 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
29060 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
29070 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
29080 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
29090 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   Statement {H131
290a0 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  20} <S60600>.**.
290b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
290c0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
290d0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
290e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
290f0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
29100 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
29110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
29120 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61  elongs.  The [da
29130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29140 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
29150 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
29160 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
29170 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29180 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74  tion] that was t
29190 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
291a0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
291b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
291c0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
291d0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
291e0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
291f0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
29200 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
29210 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  place..**.** Req
29220 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31  uirements: [H131
29230 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  23].*/.sqlite3 *
29240 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
29250 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
29260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29270 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
29280 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29290 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36  ent {H13140} <S6
292a0 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
292b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
292c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
292d0 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
292e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
292f0 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
29300 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
29310 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29320 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20  ction] pDb.  If 
29330 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
29340 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
29350 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
29360 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
29370 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
29380 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
29390 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
293a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
293b0 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72  n pDb.  If no pr
293c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
293d0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
293e0 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
293f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
29400 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
29410 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
29420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
29430 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
29440 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
29450 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
29460 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
29470 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
29480 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
29490 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
294a0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
294b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
294c0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
294d0 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31 34   [H13143] [H1314
294e0 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31 33  6] [H13149] [H13
294f0 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  152].*/.sqlite3_
29500 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
29510 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
29520 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
29530 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
29550 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
29560 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
29570 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d  llbacks {H12950}
29580 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
29590 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
295a0 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
295b0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
295c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
295d0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
295e0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
295f0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
29600 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
29610 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
29620 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
29630 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
29640 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
29650 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
29660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
29670 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
29680 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
29690 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
296a0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
296b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
296c0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
296d0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
296e0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
296f0 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
29700 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
29710 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
29720 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
29730 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
29740 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
29750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
29760 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
29770 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
29780 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
29790 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
297a0 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  k..** If the cal
297b0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
297c0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
297d0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
297e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
297f0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
29800 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
29810 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  k..**.** If anot
29820 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
29830 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
29840 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70  stered, its.** p
29850 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74  Arg value is ret
29860 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
29870 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
29880 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ed..**.** The ca
29890 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
298a0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
298b0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
298c0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
298d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
298e0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
298f0 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
29900 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
29910 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
29920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29930 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
29940 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
29950 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
29960 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
29970 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
29980 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
29990 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
299a0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
299b0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
299c0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
299d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
299e0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
299f0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
29a00 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
29a10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29a20 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
29a30 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
29a40 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
29a50 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ph..**.** Regist
29a60 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
29a70 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
29a80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
29a90 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
29aa0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
29ab0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
29ac0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
29ad0 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
29ae0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
29af0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
29b00 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
29b10 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
29b20 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
29b30 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
29b40 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
29b50 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
29b60 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
29b70 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
29b80 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
29b90 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
29ba0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
29bb0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
29bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29bd0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
29be0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
29bf0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
29c00 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
29c10 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
29c20 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
29c30 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
29c40 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
29c50 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
29c60 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
29c70 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  o>.**.** Require
29c80 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35  ments:.** [H1295
29c90 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32  1] [H12952] [H12
29ca0 39 35 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48  953] [H12954] [H
29cb0 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36  12955].** [H1296
29cc0 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32  1] [H12962] [H12
29cd0 39 36 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f  963] [H12964].*/
29ce0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
29cf0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
29d00 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
29d10 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
29d20 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
29d30 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
29d40 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
29d50 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
29d60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
29d70 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
29d80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
29d90 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e  H12970} <S60400>
29da0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
29db0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
29dc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
29dd0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
29de0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
29df0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
29e00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
29e10 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
29e20 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
29e30 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
29e40 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
29e50 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
29e60 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
29e70 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
29e80 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
29e90 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
29ea0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
29eb0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
29ec0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
29ed0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ridden..**.** Th
29ee0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
29ef0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
29f00 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
29f10 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
29f20 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
29f30 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
29f40 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66  eleted..** The f
29f50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
29f60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
29f70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
29f80 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
29f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
29fa0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68  te_hook()..** Th
29fb0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
29fc0 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
29fd0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
29fe0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
29ff0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
2a000 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
2a010 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
2a020 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
2a030 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
2a040 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
2a050 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  ed..** The third
2a060 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
2a070 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
2a080 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
2a090 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  inters to the.**
2a0a0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
2a0b0 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
2a0c0 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
2a0d0 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e   row..** The fin
2a0e0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
2a0f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
2a100 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
2a110 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20  .** In the case 
2a120 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
2a130 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
2a140 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
2a150 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
2a160 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
2a170 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
2a180 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2a190 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
2a1a0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
2a1b0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
2a1c0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
2a1d0 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
2a1e0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2a1f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a200 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2a210 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2a220 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2a230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a240 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2a250 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2a260 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2a270 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2a280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a290 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2a2a0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2a2b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2a2c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2a2d0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2a2e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2a2f0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2a300 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2a310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a320 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2a330 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2a340 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2a350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2a360 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2a370 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2a380 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2a390 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2a3a0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
2a3b0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2a3c0 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
2a3d0 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
2a3e0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
2a3f0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
2a400 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2a410 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20  ts:.** [H12971] 
2a420 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35  [H12973] [H12975
2a430 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39  ] [H12977] [H129
2a440 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31  79] [H12981] [H1
2a450 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a  2983] [H12986].*
2a460 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2a470 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2a480 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2a490 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2a4a0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2a4b0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2a4c0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2a4d0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2a4e0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2a4f0 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
2a500 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33  ager Cache {H103
2a510 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20  30} <S30900>.** 
2a520 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2a530 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64  d cache} {shared
2a540 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a   cache mode}.**.
2a550 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2a560 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2a570 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2a580 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2a590 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2a5a0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2a5b0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2a5c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a5d0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2a5e0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2a5f0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2a600 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2a610 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2a620 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2a630 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2a640 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  ent is false..**
2a650 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
2a660 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2a670 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
2a680 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2a690 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
2a6a0 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
2a6b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
2a6c0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2a6d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
2a6e0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
2a6f0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2a700 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2a710 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2a720 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
2a730 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2a740 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2a750 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2a760 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2a770 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2a780 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2a790 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2a7a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2a7b0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2a7c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a7d0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2a7e0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2a7f0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2a800 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2a810 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2a820 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
2a830 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
2a840 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
2a850 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57  shared cache.  W
2a860 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
2a870 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
2a880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2a890 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
2a8a0 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
2a8b0 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
2a8c0 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
2a8d0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
2a8e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2a8f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
2a900 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2a910 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2a920 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2a930 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2a940 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
2a950 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
2a960 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
2a970 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2a980 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2a990 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2a9a0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2a9b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2a9c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2a9d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2a9e0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2a9f0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2aa00 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2aa10 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2aa20 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2aa30 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2aa40 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65  e Mode].**.** Re
2aa50 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
2aa60 33 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48  331] [H10336] [H
2aa70 31 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a  10337] [H10339].
2aa80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2aa90 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2aaa0 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
2aab0 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
2aac0 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
2aad0 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c  emory {H17340} <
2aae0 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2aaf0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
2ab00 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
2ab10 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2ab20 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
2ab30 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2ab40 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
2ab50 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2ab60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
2ab70 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
2ab80 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
2ab90 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20  . {END}  Memory 
2aba0 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
2abb0 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
2abc0 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
2abd0 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
2abe0 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
2abf0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
2ac00 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2ac10 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2ac20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ac30 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2ac40 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2ac50 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2ac60 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2ac70 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2ac80 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2ac90 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31  ts: [H17341] [H1
2aca0 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7342].*/.int sql
2acb0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2acc0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
2acd0 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
2ace0 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
2acf0 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20  p Size {H17350} 
2ad00 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
2ad10 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
2ad20 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
2ad30 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
2ad40 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20  "soft" limit.** 
2ad50 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
2ad60 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
2ad70 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
2ad80 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2ad90 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
2ada0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
2adb0 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75  quested that wou
2adc0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2add0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2ade0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
2adf0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
2ae00 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a  invoked one or.*
2ae10 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  * more times to 
2ae20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
2ae30 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
2ae40 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66  location is perf
2ae50 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ormed..**.** The
2ae60 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2ae70 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
2ae80 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
2ae90 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
2aea0 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75  * cannot free su
2aeb0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
2aec0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
2aed0 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
2aee0 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
2aef0 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
2af00 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
2af10 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
2af20 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
2af30 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
2af40 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2af50 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2af60 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2af70 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2af80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2af90 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2afa0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2afb0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2afc0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
2afd0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2afe0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2aff0 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
2b000 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
2b010 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2b020 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2b030 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2b040 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2b050 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2b060 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2b070 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2b080 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2b090 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2b0a0 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
2b0b0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2b0c0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2b0d0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2b0e0 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2b0f0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2b100 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2b110 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2b120 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2b130 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2b140 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2b150 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2b160 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2b170 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2b180 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2b190 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2b1a0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2b1b0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2b1c0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2b1d0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2b1e0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2b1f0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2b200 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2b210 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2b220 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2b230 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2b240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2b250 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2b260 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2b270 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2b280 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2b290 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2b2a0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2b2b0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2b2c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2b2d0 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b  s:.** [H16351] [
2b2e0 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d  H16352] [H16353]
2b2f0 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35   [H16354] [H1635
2b300 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76  5] [H16358].*/.v
2b310 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2b320 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2b330 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b340 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
2b350 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
2b360 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48  mn Of A Table {H
2b370 31 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a  12850} <S60300>.
2b380 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b390 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2b3a0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2b3b0 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2b3c0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2b3d0 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2b3e0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2b3f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b400 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2b410 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2b420 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2b430 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2b440 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
2b450 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
2b460 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
2b470 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2b480 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
2b490 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e  ction. The secon
2b4a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
2b4b0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
2b4c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2b4d0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
2b4e0 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74  "temp" or an att
2b4f0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
2b500 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
2b510 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
2b520 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74  e or NULL. If it
2b530 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
2b540 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
2b550 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
2b560 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
2b570 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
2b580 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
2b590 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2b5a0 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
2b5b0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
2b5c0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
2b5d0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
2b5e0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2b5f0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2b600 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
2b610 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
2b620 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
2b630 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
2b640 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
2b650 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
2b660 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
2b670 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
2b680 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20  .** Metadata is 
2b690 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
2b6a0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
2b6b0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
2b6c0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
2b6d0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2b6e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2b6f0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
2b700 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
2b710 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
2b720 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
2b730 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2b740 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
2b750 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
2b760 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed..**.** <block
2b770 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2b780 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2b790 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2b7a0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2b7b0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2b7c0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2b7d0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2b7e0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2b7f0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2b800 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2b810 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2b820 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2b830 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2b840 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2b850 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2b860 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2b870 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2b880 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2b890 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2b8a0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2b8b0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2b8c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2b8d0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2b8e0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2b8f0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2b900 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2b910 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2b920 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2b930 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2b940 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
2b950 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2b960 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2b970 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2b980 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2b990 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2b9a0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2b9b0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2b9c0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2b9d0 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2b9e0 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2b9f0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2ba00 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
2ba10 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
2ba20 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
2ba30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2ba40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2ba50 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2ba60 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2ba70 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2ba80 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2ba90 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2baa0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2bab0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2bac0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2bad0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2bae0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2baf0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2bb00 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2bb10 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69  lumn. If there i
2bb20 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2bb30 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2bb40 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2bb50 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2bb60 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2bb70 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2bb80 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2bb90 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2bba0 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2bbb0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2bbc0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2bbd0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2bbe0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2bbf0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2bc00 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2bc10 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2bc20 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
2bc30 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
2bc40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
2bc50 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
2bc60 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
2bc70 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
2bc80 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
2bc90 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
2bca0 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
2bcb0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
2bcc0 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
2bcd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2bce0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
2bcf0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
2bd00 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
2bd10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bd20 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
2bd30 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
2bd40 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
2bd50 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
2bd60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2bd70 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2bd80 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2bd90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2bda0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2bdb0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2bdc0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
2bdd0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2bde0 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
2bdf0 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
2be00 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2be10 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
2be20 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
2be30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2be40 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
2be50 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
2be60 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
2be70 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
2be80 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
2be90 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
2bea0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
2beb0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
2bec0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
2bed0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
2bee0 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
2bef0 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
2bf00 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
2bf10 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
2bf20 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
2bf30 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
2bf40 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
2bf50 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
2bf60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2bf70 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
2bf80 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2bf90 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
2bfa0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
2bfb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2bfc0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
2bfd0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
2bfe0 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
2bff0 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
2c000 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2c010 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
2c020 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
2c030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c040 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
2c050 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53  sion {H12600} <S
2c060 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2c070 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
2c080 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
2c090 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
2c0a0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
2c0b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31  e..**.** {H12601
2c0c0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2c0d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2c0e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2c0f0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2c100 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
2c110 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2c120 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
2c130 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
2c140 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68  *.** {H12602} Th
2c150 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
2c160 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zProc..**.** {H
2c170 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
2c180 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
2c190 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
2c1a0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
2c1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
2c1c0 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
2c1d0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
2c1e0 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34  "..**.** {H12604
2c1f0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
2c200 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2c210 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
2c220 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2c230 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e    [SQLITE_OK] on
2c240 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2c250 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2c260 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2c270 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ong..**.** {H126
2c280 30 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20  05} If an error 
2c290 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
2c2a0 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
2c2b0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
2c2c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64     [sqlite3_load
2c2d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2c2e0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2c2f0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20  tempt to.**     
2c300 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72       fill *pzErr
2c310 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d  Msg with error m
2c320 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
2c330 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
2c340 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65           obtaine
2c350 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2c360 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d  malloc()]. {END}
2c370 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
2c380 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2c390 20 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74     should free t
2c3a0 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
2c3b0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
2c3c0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ree()]..**.** {H
2c3d0 31 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e  12606} Extension
2c3e0 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
2c3f0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
2c400 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2c410 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2c420 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2c430 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
2c440 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20  is API,.**      
2c450 20 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e      otherwise an
2c460 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2c470 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  eturned..*/.int 
2c480 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2c490 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
2c4a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2c4b0 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
2c4c0 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
2c4d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c4e0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2c4f0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
2c500 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
2c510 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
2c520 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
2c530 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2c540 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
2c550 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
2c560 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
2c570 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
2c580 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
2c590 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
2c5a0 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
2c5b0 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
2c5c0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2c5d0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
2c5e0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
2c5f0 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e  H12620} <S20500>
2c600 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74  .**.** So as not
2c610 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
2c620 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
2c630 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
2c640 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
2c650 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
2c660 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
2c670 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
2c680 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
2c690 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
2c6a0 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
2c6b0 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
2c6c0 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
2c6d0 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73  lowing API.** is
2c6e0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
2c6f0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
2c700 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2c710 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
2c720 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74  d off..**.** Ext
2c730 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
2c740 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
2c750 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
2c760 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32  63..**.** {H1262
2c770 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  1} Call the sqli
2c780 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2c790 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
2c7a0 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
2c7b0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  1.**          to
2c7c0 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
2c7d0 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
2c7e0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
2c7f0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
2c800 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b           it back
2c810 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a   off again..**.*
2c820 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e  * {H12622} Exten
2c830 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
2c840 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  off by default..
2c850 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2c860 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2c870 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
2c880 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
2c890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2c8a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
2c8b0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20  d An Extensions 
2c8c0 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30  {H12640} <S20500
2c8d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  >.**.** This API
2c8e0 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20   can be invoked 
2c8f0 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74  at program start
2c900 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  up in order to r
2c910 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  egister.** one o
2c920 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c  r more staticall
2c930 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69  y linked extensi
2c940 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  ons that will be
2c950 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f   available.** to
2c960 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61   all new [databa
2c970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e  se connections].
2c980 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2c990 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2c9a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c9b0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
2c9c0 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a  n array that is.
2c9d0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
2c9e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c9f0 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e  ()].  If you run
2ca00 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63   a memory leak c
2ca10 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75  hecker.** on you
2ca20 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
2ca30 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
2ca40 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20  because of this 
2ca50 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a  array, invoke.**
2ca60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
2ca70 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2ca80 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64  ] prior to shutd
2ca90 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
2caa0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
2cab0 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63  12641} This func
2cac0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61  tion registers a
2cad0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  n extension entr
2cae0 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a  y point that is.
2caf0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2cb00 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
2cb10 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
2cb20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cb30 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
2cb40 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69     is opened usi
2cb50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
2cb60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2cb70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
2cb80 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2cb90 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
2cba0 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c  ** {H12642} Dupl
2cbb0 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
2cbc0 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
2cbd0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
2cbe0 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20  utine.**        
2cbf0 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73    multiple times
2cc00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65   with the same e
2cc10 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d  xtension is harm
2cc20 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  less..**.** {H12
2cc30 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e  643} This routin
2cc40 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
2cc50 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
2cc60 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a  ion in an array.
2cc70 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
2cc80 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2cc90 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2cca0 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  c()]..**.** {H12
2ccb0 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
2ccc0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2ccd0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2cce0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2ccf0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2cd00 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
2cd10 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
2cd20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2cd30 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
2cd40 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2cd50 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30   {H12660} <S2050
2cd60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
2cd70 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2cd80 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2cd90 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
2cda0 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
2cdb0 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64  s. {END}  It und
2cdc0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
2cdd0 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b  f all prior.** [
2cde0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
2cdf0 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e  ension()] calls.
2ce00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20  .**.** {H12661} 
2ce10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
2ce20 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69  sables all previ
2ce30 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
2ce40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2ce50 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2ce60 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32  s..**.** {H12662
2ce70 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2ce80 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
2ce90 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
2cea0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2ceb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2cec0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2ced0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
2cee0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
2cef0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
2cf00 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
2cf10 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
2cf20 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
2cf30 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
2cf40 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2cf50 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
2cf60 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
2cf70 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
2cf80 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
2cf90 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
2cfa0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
2cfb0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
2cfc0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
2cfd0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
2cfe0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
2cff0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
2d000 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
2d010 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2d020 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
2d030 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
2d040 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
2d050 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
2d060 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
2d070 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
2d080 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
2d090 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
2d0a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
2d0b0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
2d0c0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
2d0d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2d0e0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
2d0f0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
2d100 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2d110 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
2d120 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
2d130 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2d140 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
2d150 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
2d160 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2d170 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
2d180 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
2d190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d1a0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
2d1b0 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53  ject {H18000} <S
2d1c0 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2d1d0 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
2d1e0 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  le.** EXPERIMENT
2d1f0 41 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c  AL.**.** A modul
2d200 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20  e is a class of 
2d210 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20  virtual tables. 
2d220 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20   Each module is 
2d230 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e  defined.** by an
2d240 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
2d250 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
2d260 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75  ture.  This stru
2d270 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a  cture consists.*
2d280 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  * mostly of meth
2d290 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
2d2a0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2d2b0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
2d2c0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
2d2d0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
2d2e0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
2d2f0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2d300 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
2d310 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
2d320 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
2d330 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
2d340 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
2d350 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
2d360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2d370 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
2d380 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
2d390 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d3a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
2d3b0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
2d3c0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
2d3d0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
2d3e0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
2d3f0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2d400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
2d410 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
2d420 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
2d430 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
2d440 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
2d450 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
2d460 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2d470 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2d480 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
2d490 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
2d4a0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2d4b0 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
2d4c0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
2d4d0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2d4e0 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
2d4f0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2d500 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2d510 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
2d520 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
2d530 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2d540 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
2d550 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
2d560 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
2d570 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
2d580 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
2d590 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2d5a0 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
2d5b0 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
2d5c0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
2d5d0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d5e0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
2d5f0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2d600 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2d610 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
2d620 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2d630 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d640 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
2d650 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
2d660 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
2d670 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
2d680 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
2d690 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
2d6a0 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
2d6b0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
2d6c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
2d6d0 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
2d6e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2d6f0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
2d700 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
2d710 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d720 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
2d730 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2d740 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
2d750 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
2d760 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d770 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
2d780 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2d790 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
2d7a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2d7b0 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
2d7c0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
2d7d0 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
2d7e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2d7f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2d800 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d810 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
2d820 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
2d830 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
2d840 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
2d850 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
2d860 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
2d870 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
2d880 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
2d890 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d  rmation {H18100}
2d8a0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2d8b0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
2d8c0 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50  ndex_info.** EXP
2d8d0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2d8e0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
2d8f0 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
2d900 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
2d910 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74  ctures is used t
2d920 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
2d930 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
2d940 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
2d950 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49   from the xBestI
2d960 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ndex.** method o
2d970 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64  f an sqlite3_mod
2d980 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73  ule.  The fields
2d990 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
2d9a0 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
2d9b0 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
2d9c0 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
2d9d0 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
2d9e0 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
2d9f0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
2da00 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
2da10 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  lds..**.** The a
2da20 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
2da30 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
2da40 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2da50 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
2da60 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
2da70 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
2da80 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
2da90 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
2daa0 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
2dab0 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c  =.  The particul
2dac0 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
2dad0 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
2dae0 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
2daf0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2db00 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
2db10 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
2db20 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61  nt[].iColumn.  a
2db30 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
2db40 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
2db50 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
2db60 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
2db70 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
2db80 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
2db90 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
2dba0 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
2dbb0 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
2dbc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69  ..**.** The opti
2dbd0 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
2dbe0 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
2dbf0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
2dc00 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
2dc10 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
2dc20 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
2dc30 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
2dc40 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
2dc50 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
2dc60 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
2dc70 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
2dc80 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
2dc90 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
2dca0 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
2dcb0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
2dcc0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
2dcd0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
2dce0 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
2dcf0 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
2dd00 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
2dd10 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
2dd20 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
2dd30 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  * Information ab
2dd40 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
2dd50 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
2dd60 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
2dd70 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66  .** Each term of
2dd80 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
2dd90 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
2dda0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2ddb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65  e..**.** The xBe
2ddc0 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d  stIndex method m
2ddd0 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
2dde0 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
2ddf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2de00 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
2de10 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
2de20 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72   xFilter.  If ar
2de30 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
2de40 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
2de50 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
2de60 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
2de70 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
2de80 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
2de90 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
2dea0 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
2deb0 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72  rgv.  If aConstr
2dec0 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
2ded0 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
2dee0 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
2def0 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
2df00 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
2df10 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
2df20 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
2df30 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
2df40 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
2df50 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  * The idxNum and
2df60 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
2df70 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
2df80 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c  passed into xFil
2df90 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ter..** sqlite3_
2dfa0 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74  free() is used t
2dfb0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
2dfc0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
2dfd0 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
2dfe0 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73   The orderByCons
2dff0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
2e000 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c  output from xFil
2e010 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  ter will occur i
2e020 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
2e030 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
2e040 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
2e050 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
2e060 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
2e070 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
2e080 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
2e090 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
2e0a0 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
2e0b0 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
2e0c0 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
2e0d0 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
2e0e0 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
2e0f0 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
2e100 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
2e110 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
2e120 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
2e130 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
2e140 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
2e150 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
2e160 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
2e170 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a  ately log(N)..**
2e180 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2e190 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
2e1a0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
2e1b0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
2e1c0 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
2e1d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2e1e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63  SQLite..*/.struc
2e1f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e200 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
2e210 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
2e220 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
2e230 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
2e240 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
2e250 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
2e260 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2e270 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
2e280 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
2e290 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e2a0 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
2e2b0 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
2e2c0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
2e2d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
2e2e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
2e2f0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
2e300 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
2e310 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
2e320 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
2e330 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
2e340 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
2e350 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
2e360 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
2e370 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
2e380 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
2e390 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
2e3a0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
2e3b0 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
2e3c0 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
2e3d0 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
2e3e0 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
2e3f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
2e400 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2e410 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
2e420 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
2e430 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e440 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
2e450 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
2e460 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
2e470 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
2e480 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
2e490 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
2e4a0 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
2e4b0 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
2e4c0 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
2e4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e4e0 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
2e4f0 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
2e500 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
2e510 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
2e520 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
2e530 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
2e540 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
2e550 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
2e560 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
2e570 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
2e580 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
2e590 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
2e5a0 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
2e5b0 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
2e5c0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
2e5d0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
2e5e0 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
2e5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e600 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
2e610 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
2e620 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
2e630 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
2e640 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
2e650 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
2e660 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
2e670 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
2e680 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
2e690 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
2e6a0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
2e6b0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
2e6c0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
2e6d0 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
2e6e0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
2e6f0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
2e700 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
2e710 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
2e720 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
2e730 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
2e740 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
2e750 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
2e760 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2e770 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
2e780 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2e790 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
2e7a0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2e7b0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2e7c0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
2e7d0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2e7e0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
2e7f0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
2e800 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2e810 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
2e820 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2e830 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
2e840 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
2e850 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
2e860 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
2e870 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b  Implementation {
2e880 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18200} <S20400>
2e890 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2e8a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e8b0 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
2e8c0 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f  egister a new mo
2e8d0 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61  dule name with a
2e8e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2e8f0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75  nnection].  Modu
2e900 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
2e910 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
2e920 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 6e  re.** creating n
2e930 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
2e940 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c  s on the module,
2e950 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67   or before using
2e960 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
2e970 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f  virtual tables o
2e980 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  f the module..**
2e990 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2e9a0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
2e9b0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
2e9c0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
2e9d0 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
2e9e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2e9f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
2ea00 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
2ea10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2ea20 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
2ea30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ea40 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
2ea50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
2ea60 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
2ea70 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
2ea80 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
2ea90 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
2eaa0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
2eab0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
2eac0 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74  ule *,    /* Met
2ead0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
2eae0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20  ule */.  void * 
2eaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2eb00 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
2eb10 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
2eb20 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f  Connect */.);../
2eb30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2eb40 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
2eb50 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
2eb60 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20  tation {H18210} 
2eb70 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20400>.** EXPE
2eb80 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2eb90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
2eba0 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20  dentical to the 
2ebb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ebc0 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64  module()] method
2ebd0 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70   above,.** excep
2ebe0 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73  t that it allows
2ebf0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
2ec00 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65  nction to be spe
2ec10 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a  cified. It is.**
2ec20 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72   even more exper
2ec30 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65  imental than the
2ec40 20 72 65 73 74 20 6f 66 20 74 68 65 20 76 69 72   rest of the vir
2ec50 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e  tual tables API.
2ec60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
2ec70 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
2ec80 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2ec90 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2eca0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ecb0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
2ecc0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
2ecd0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
2ece0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ecf0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
2ed00 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
2ed10 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
2ed20 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2ed30 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
2ed40 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
2ed50 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
2ed60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ed70 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
2ed80 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
2ed90 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
2eda0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
2edb0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
2edc0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
2edd0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
2ede0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
2edf0 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
2ee00 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20  Object {H18010} 
2ee10 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
2ee20 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
2ee30 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ab.** EXPERIMENT
2ee40 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d  AL.**.** Every m
2ee50 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
2ee60 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
2ee70 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c  lass of the foll
2ee80 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a  owing structure.
2ee90 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ** to describe a
2eea0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
2eeb0 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  ance of the modu
2eec0 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61  le.  Each subcla
2eed0 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61  ss will.** be ta
2eee0 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70  ilored to the sp
2eef0 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20  ecific needs of 
2ef00 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  the module imple
2ef10 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68  mentation..** Th
2ef20 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  e purpose of thi
2ef30 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
2ef40 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
2ef50 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
2ef60 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61  e.** common to a
2ef70 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
2ef80 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
2ef90 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
2efa0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
2efb0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2efc0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
2efd0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
2efe0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2eff0 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a  _mprintf()] to z
2f000 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74  ErrMsg.  The met
2f010 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61  hod should.** ta
2f020 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79  ke care that any
2f030 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73   prior string is
2f040 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c   freed by a call
2f050 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
2f060 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  e()].** prior to
2f070 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77   assigning a new
2f080 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d   string to zErrM
2f090 73 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65  sg.  After the e
2f0a0 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
2f0b0 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20  is delivered up 
2f0c0 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70  to the client ap
2f0d0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73  plication, the s
2f0e0 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75  tring will be au
2f0f0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66  tomatically.** f
2f100 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  reed by sqlite3_
2f110 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a  free() and the z
2f120 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c  ErrMsg field wil
2f130 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f  l be zeroed.  No
2f140 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74  te.** that sqlit
2f150 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
2f160 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2f170 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20  are used on the 
2f180 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a  zErrMsg field.**
2f190 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74   since virtual t
2f1a0 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e  ables are common
2f1b0 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  ly implemented i
2f1c0 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e  n loadable exten
2f1d0 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64  sions which.** d
2f1e0 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  o not have acces
2f1f0 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69  s to sqlite3MPri
2f200 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ntf() or sqlite3
2f210 46 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  Free()..**.** Th
2f220 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
2f230 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
2f240 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
2f250 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f  hange or.** remo
2f260 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65  val in future re
2f270 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2f280 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
2f290 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
2f2a0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
2f2b0 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
2f2c0 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
2f2d0 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
2f2e0 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
2f2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f300 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
2f310 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63  nternally */.  c
2f320 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
2f330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2f340 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
2f350 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
2f360 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
2f370 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
2f380 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
2f390 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
2f3a0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
2f3b0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
2f3c0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
2f3d0 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
2f3e0 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c  ject  {H18020} <
2f3f0 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
2f400 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
2f410 62 5f 63 75 72 73 6f 72 0a 2a 2a 20 45 58 50 45  b_cursor.** EXPE
2f420 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45  RIMENTAL.**.** E
2f430 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  very module impl
2f440 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
2f450 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
2f460 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
2f470 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63  cture.** to desc
2f480 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61  ribe cursors tha
2f490 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65  t point into the
2f4a0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
2f4b0 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74  nd are used.** t
2f4c0 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74  o loop through t
2f4d0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2f4e0 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63  .  Cursors are c
2f4f0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2f500 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  .** xOpen method
2f510 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
2f520 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
2f530 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2f540 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
2f550 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
2f560 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
2f570 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
2f580 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
2f590 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
2f5a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
2f5b0 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
2f5c0 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
2f5d0 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
2f5e0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
2f5f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ns..**.** This i
2f600 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
2f610 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
2f620 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
2f630 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
2f640 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
2f650 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
2f660 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
2f670 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
2f680 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2f690 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
2f6a0 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
2f6b0 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
2f6c0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
2f6d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2f6e0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
2f6f0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
2f700 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
2f710 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2f720 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
2f730 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
2f740 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34  e {H18280} <S204
2f750 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
2f760 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43  TAL.**.** The xC
2f770 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
2f780 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20  ct methods of a 
2f790 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66  module use the f
2f7a0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
2f7b0 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
2f7c0 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
2f7d0 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
2f7e0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
2f7f0 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
2f800 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
2f810 6c 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  lement..**.** Th
2f820 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
2f830 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
2f840 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
2f850 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f  hange or.** remo
2f860 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65  val in future re
2f870 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2f880 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
2f890 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
2f8a0 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
2f8b0 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  b(sqlite3*, cons
2f8c0 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54  t char *zCreateT
2f8d0 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  able);../*.** CA
2f8e0 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
2f8f0 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
2f900 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
2f910 7b 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30  {H18300} <S20400
2f920 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
2f930 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  L.**.** Virtual 
2f940 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
2f950 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
2f960 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2f970 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
2f980 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75  sing the xFindFu
2f990 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20  nction method.  
2f9a0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
2f9b0 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
2f9c0 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
2f9d0 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
2f9e0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   be overloaded..
2f9f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d  **.** This API m
2fa00 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
2fa10 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
2fa20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2fa30 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
2fa40 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
2fa50 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
2fa60 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
2fa70 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
2fa80 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
2fa90 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
2faa0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
2fab0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d  created.  The im
2fac0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
2fad0 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
2fae0 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
2faf0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
2fb00 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
2fb10 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
2fb20 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
2fb30 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
2fb40 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
2fb50 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
2fb60 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
2fb70 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
2fb80 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
2fb90 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
2fba0 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
2fbb0 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
2fbc0 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
2fbd0 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
2fbe0 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
2fbf0 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
2fc00 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
2fc10 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
2fc20 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ge..*/.SQLITE_EX
2fc30 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
2fc40 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
2fc50 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
2fc60 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2fc70 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
2fc80 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
2fc90 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
2fca0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
2fcb0 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
2fcc0 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
2fcd0 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
2fce0 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
2fcf0 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
2fd00 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
2fd10 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
2fd20 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
2fd30 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
2fd40 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
2fd50 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
2fd60 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
2fd70 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
2fd80 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
2fd90 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
2fda0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
2fdb0 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
2fdc0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
2fdd0 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
2fde0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
2fdf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
2fe00 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
2fe10 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
2fe20 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
2fe30 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
2fe40 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
2fe50 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2fe60 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
2fe70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
2fe80 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2fe90 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
2fea0 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37  n Open BLOB {H17
2feb0 38 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  800} <S30230>.**
2fec0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
2fed0 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
2fee0 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
2fef0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
2ff00 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
2ff10 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
2ff20 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
2ff30 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2ff40 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2ff50 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
2ff60 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a  erformed..** Obj
2ff70 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
2ff80 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
2ff90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2ffa0 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
2ffb0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2ffc0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
2ffd0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2ffe0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
2fff0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
30000 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
30010 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
30020 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
30030 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
30040 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42  ections of the B
30050 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  LOB..** The [sql
30060 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
30070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
30080 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
30090 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
300a0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
300b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
300c0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
300d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
300e0 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
300f0 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
30100 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32  O {H17810} <S302
30110 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  30>.**.** This i
30120 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
30130 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
30140 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
30150 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
30160 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
30170 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
30180 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
30190 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
301a0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
301b0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
301c0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
301d0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
301e0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
301f0 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
30200 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
30210 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
30220 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
30230 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
30240 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
30250 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65  on-zero, the the
30260 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
30270 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
30280 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66  write access. If
30290 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
302a0 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
302b0 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e  for read access.
302c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
302d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
302e0 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69  me is not the fi
302f0 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74  lename that cont
30300 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  ains.** the data
30310 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20  base but rather 
30320 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
30330 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
30340 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73  e that.** is ass
30350 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64  igned when the d
30360 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
30370 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
30380 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  CH]..** For the 
30390 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
303a0 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  le, the database
303b0 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e   name is "main".
303c0 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62  .** For TEMP tab
303d0 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73  les, the databas
303e0 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22  e name is "temp"
303f0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
30400 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
30410 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
30420 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61  the new [BLOB ha
30430 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e  ndle] is written
30440 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20  .** to *ppBlob. 
30450 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
30460 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
30470 75 72 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61  urned and any va
30480 6c 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74  lue written.** t
30490 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
304a0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
304b0 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54  the caller..** T
304c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
304d0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
304e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f  connection] erro
304f0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
30500 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
30510 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
30520 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
30530 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
30540 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f  .**.** If the ro
30550 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
30560 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
30570 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
30580 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
30590 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
305a0 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
305b0 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
305c0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
305d0 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
305e0 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
305f0 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
30600 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
30610 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
30620 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
30630 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
30640 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
30650 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a  e is open on..**
30660 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
30670 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
30680 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
30690 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a  b_write()] for.*
306a0 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42  * a expired BLOB
306b0 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74   handle fail wit
306c0 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65  h an return code
306d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
306e0 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77  T]..** Changes w
306f0 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c  ritten into a BL
30700 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  OB prior to the 
30710 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72  BLOB expiring ar
30720 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63  e not.** rollbac
30730 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
30740 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
30750 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
30760 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
30770 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
30780 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
30790 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
307a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ion..**.** Requi
307b0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
307c0 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48  813] [H17814] [H
307d0 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20  17816] [H17819] 
307e0 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34  [H17821] [H17824
307f0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
30800 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
30810 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
30820 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
30830 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
30840 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30850 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
30860 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
30870 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
30880 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
30890 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
308a0 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
308b0 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38  LOB Handle {H178
308c0 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  30} <S30230>.**.
308d0 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65  ** Closes an ope
308e0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e  n [BLOB handle].
308f0 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61  .**.** Closing a
30900 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
30910 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
30920 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
30930 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
30940 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
30950 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
30960 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30970 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
30980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30990 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
309a0 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49  mmit mode]..** I
309b0 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72  f any writes wer
309c0 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c  e made to the BL
309d0 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62  OB, they might b
309e0 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a  e held in cache.
309f0 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f  ** until the clo
30a00 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20  se operation if 
30a10 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b  they will fit. {
30a20 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69  END}.**.** Closi
30a30 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
30a40 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
30a50 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
30a60 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
30a70 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
30a80 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
30a90 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
30aa0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
30ab0 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
30ac0 64 2e 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79  d.  {H17833} Any
30ad0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
30ae0 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
30af0 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
30b00 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
30b10 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a  return value..**
30b20 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20  .** The BLOB is 
30b30 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
30b40 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
30b50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
30b60 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
30b70 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
30b80 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
30b90 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
30ba0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33  ents:.** [H17833
30bb0 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38  ] [H17836] [H178
30bc0 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  39].*/.int sqlit
30bd0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
30be0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
30bf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30c00 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
30c10 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  Of An Open BLOB 
30c20 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30  {H17840} <S30230
30c30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  >.**.** Returns 
30c40 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
30c50 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
30c60 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
30c70 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20   open.** []BLOB 
30c80 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f  handle] in its o
30c90 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  nly argument..**
30ca0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
30cb0 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f  :.** [H17843].*/
30cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
30cd0 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  b_bytes(sqlite3_
30ce0 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
30cf0 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44  CAPI3REF: Read D
30d00 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20  ata From A BLOB 
30d10 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48  Incrementally {H
30d20 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17850} <S30230>.
30d30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
30d40 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
30d50 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
30d60 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
30d70 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61  le] into a.** ca
30d80 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
30d90 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66  ffer. N bytes of
30da0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
30db0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a   into buffer Z.*
30dc0 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20  * from the open 
30dd0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61  BLOB, starting a
30de0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
30df0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65  ..**.** If offse
30e00 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
30e10 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
30e20 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
30e30 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
30e40 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
30e50 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
30e60 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20  ta is read.  If 
30e70 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a  N or iOffset is.
30e80 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
30e90 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  o, [SQLITE_ERROR
30ea0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
30eb0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
30ec0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65  d..**.** An atte
30ed0 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d  mpt to read from
30ee0 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
30ef0 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
30f00 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
30f10 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
30f20 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f  _ABORT]..**.** O
30f30 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
30f40 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
30f50 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
30f60 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
30f70 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
30f80 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
30f90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  eturned..**.** R
30fa0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
30fb0 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36  [H17853] [H17856
30fc0 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38  ] [H17859] [H178
30fd0 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31  62] [H17863] [H1
30fe0 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a  7865] [H17868].*
30ff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
31000 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f  ob_read(sqlite3_
31010 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c  blob *, void *Z,
31020 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66   int N, int iOff
31030 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
31040 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74  I3REF: Write Dat
31050 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
31060 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37  crementally {H17
31070 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  870} <S30230>.**
31080 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
31090 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
310a0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
310b0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
310c0 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
310d0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
310e0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
310f0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
31100 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20  from the buffer 
31110 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70  Z.** into the op
31120 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
31130 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
31140 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  set..**.** If th
31150 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
31160 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
31170 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73  rst argument was
31180 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a   not opened for.
31190 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  ** writing (the 
311a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
311b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
311c0 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72  _open()] was zer
311d0 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  o),.** this func
311e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
311f0 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
31200 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
31210 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
31220 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
31230 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
31240 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
31250 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
31260 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
31270 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
31280 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20  I..** If offset 
31290 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
312a0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
312b0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
312c0 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
312d0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
312e0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
312f0 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66   is written.  If
31300 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
31310 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
31320 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
31330 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
31340 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  s written..**.**
31350 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77   An attempt to w
31360 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
31370 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
31380 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
31390 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
313a0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
313b0 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42   Writes to the B
313c0 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
313d0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
313e0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
313f0 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
31400 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
31410 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
31420 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
31430 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
31440 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
31450 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
31460 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
31470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
31480 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
31490 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
314a0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
314b0 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
314c0 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
314d0 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
314e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
314f0 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
31500 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
31510 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
31520 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
31530 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
31540 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33  ents:.** [H17873
31550 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38  ] [H17874] [H178
31560 37 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31  75] [H17876] [H1
31570 37 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b  7877] [H17879] [
31580 48 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d  H17882] [H17885]
31590 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a  .** [H17888].*/.
315a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
315b0 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
315c0 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
315d0 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
315e0 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
315f0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
31600 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
31610 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d  Objects {H11200}
31620 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20100>.**.** 
31630 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
31640 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
31650 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
31660 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
31670 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
31680 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
31690 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
316a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
316b0 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c  Most SQLite buil
316c0 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a  ds come with a.*
316d0 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74  * single default
316e0 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70   VFS that is app
316f0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65  ropriate for the
31700 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
31710 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e  ** New VFSes can
31720 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
31730 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65  nd existing VFSe
31740 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73  s can be unregis
31750 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f  tered..** The fo
31760 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
31770 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e  es are provided.
31780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31790 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
317a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
317b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
317c0 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  FS given its nam
317d0 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20  e..** Names are 
317e0 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a  case sensitive..
317f0 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72  ** Names are zer
31800 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
31810 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49  -8 strings..** I
31820 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61  f there is no ma
31830 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  tch, a NULL poin
31840 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
31850 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20  .** If zVfsName 
31860 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
31870 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
31880 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
31890 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65  New VFSes are re
318a0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71  gistered with sq
318b0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
318c0 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65  er()..** Each ne
318d0 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
318e0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
318f0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
31900 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68  ag is set..** Th
31910 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
31920 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
31930 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
31940 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54  out injury..** T
31950 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69  o make an existi
31960 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20  ng VFS into the 
31970 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67  default VFS, reg
31980 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a  ister it again.*
31990 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44  * with the makeD
319a0 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49  flt flag set.  I
319b0 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20  f two different 
319c0 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a  VFSes with the.*
319d0 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  * same name are 
319e0 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20  registered, the 
319f0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
31a00 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20  fined.  If a.** 
31a10 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65  VFS is registere
31a20 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68  d with a name th
31a30 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  at is NULL or an
31a40 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a   empty string,.*
31a50 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
31a60 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
31a70 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74  ..**.** Unregist
31a80 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
31a90 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
31aa0 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
31ab0 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20  face..** If the 
31ac0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
31ad0 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
31ae0 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
31af0 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
31b00 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
31b10 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
31b20 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  S is arbitrary..
31b30 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
31b40 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20  ts:.** [H11203] 
31b50 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39  [H11206] [H11209
31b60 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32  ] [H11212] [H112
31b70 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a  15] [H11218].*/.
31b80 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c  sqlite3_vfs *sql
31b90 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f  ite3_vfs_find(co
31ba0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61  nst char *zVfsNa
31bb0 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  me);.int sqlite3
31bc0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71  _vfs_register(sq
31bd0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
31be0 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73  makeDflt);.int s
31bf0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
31c00 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
31c10 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s*);../*.** CAPI
31c20 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48  3REF: Mutexes {H
31c30 31 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17000} <S20000>.
31c40 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
31c50 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
31c60 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68   routines for th
31c70 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e  read.** synchron
31c80 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20  ization. Though 
31c90 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65  they are intende
31ca0 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  d for internal.*
31cb0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c  * use by SQLite,
31cc0 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73   code that links
31cd0 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20   against SQLite 
31ce0 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20  is.** permitted 
31cf0 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68  to use any of th
31d00 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
31d10 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73  .** The SQLite s
31d20 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61  ource code conta
31d30 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ins multiple imp
31d40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
31d50 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72  of these mutex r
31d60 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70  outines.  An app
31d70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65  ropriate impleme
31d80 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65  ntation.** is se
31d90 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63  lected automatic
31da0 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d  ally at compile-
31db0 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  time.  The follo
31dc0 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  wing.** implemen
31dd0 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  tations are avai
31de0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c  lable in the SQL
31df0 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20  ite core:.**.** 
31e00 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  <ul>.** <li>   S
31e10 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a  QLITE_MUTEX_OS2.
31e20 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
31e30 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a  _MUTEX_PTHREAD.*
31e40 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
31e50 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69  MUTEX_W32.** <li
31e60 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
31e70 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  _NOOP.** </ul>.*
31e80 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
31e90 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65  MUTEX_NOOP imple
31ea0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73  mentation is a s
31eb0 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a  et of routines.*
31ec0 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72  * that does no r
31ed0 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20  eal locking and 
31ee0 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
31ef0 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73  or use in.** a s
31f00 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
31f10 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
31f20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
31f30 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
31f40 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
31f50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
31f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31f70 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
31f80 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f  ate for use on O
31f90 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57  S/2, Unix, and W
31fa0 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  indows..**.** If
31fb0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
31fc0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
31fd0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
31fe0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
31ff0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
32000 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
32010 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
32020 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
32030 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32040 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
32050 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49  h the library. I
32060 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a  n this case the.
32070 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  ** application m
32080 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73  ust supply a cus
32090 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  tom mutex implem
320a0 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74  entation using t
320b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
320c0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
320d0 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  on of the sqlite
320e0 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74  3_config() funct
320f0 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61  ion.** before ca
32100 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e  lling sqlite3_in
32110 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e  itialize() or an
32120 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73  y other public s
32130 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74  qlite3_.** funct
32140 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73  ion that calls s
32150 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
32160 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  e()..**.** {H170
32170 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  11} The sqlite3_
32180 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f  mutex_alloc() ro
32190 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20  utine allocates 
321a0 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61  a new.** mutex a
321b0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
321c0 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37  nter to it. {H17
321d0 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72  012} If it retur
321e0 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
321f0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
32200 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
32210 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30  allocated. {H170
32220 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  13} SQLite.** wi
32230 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
32240 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
32250 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34  n error. {H17014
32260 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  } The argument.*
32270 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
32280 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
32290 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
322a0 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
322b0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
322c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
322d0 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
322e0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
322f0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
32300 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
32310 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
32320 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
32330 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
32340 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
32350 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
32360 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
32370 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
32380 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
32390 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
323a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
323b0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a  TEX_STATIC_LRU2.
323c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b  ** </ul>.**.** {
323d0 48 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73  H17015} The firs
323e0 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  t two constants 
323f0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
32400 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
32410 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
32420 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d  utex.  The new m
32430 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76  utex is recursiv
32440 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  e when SQLITE_MU
32450 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
32460 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74   is used but not
32470 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20   necessarily so 
32480 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
32490 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20  X_FAST is used. 
324a0 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74  {END}.** The mut
324b0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
324c0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
324d0 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e  to make a distin
324e0 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
324f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
32500 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49  CURSIVE and SQLI
32510 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66  TE_MUTEX_FAST if
32520 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
32530 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31  want to.  {H1701
32540 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69  6} But SQLite wi
32550 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
32560 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
32570 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
32580 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
32590 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20  eds one.  {END} 
325a0 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d  If a faster non-
325b0 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a  recursive mutex.
325c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
325d0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  n is available o
325e0 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66  n the host platf
325f0 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73  orm, the mutex s
32600 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68  ubsystem.** migh
32610 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20  t return such a 
32620 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73  mutex in respons
32630 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  e to SQLITE_MUTE
32640 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48  X_FAST..**.** {H
32650 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72  17017} The other
32660 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74   allowed paramet
32670 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ers to sqlite3_m
32680 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63  utex_alloc() eac
32690 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f  h return.** a po
326a0 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69  inter to a stati
326b0 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75  c preexisting mu
326c0 74 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72  tex. {END}  Four
326d0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
326e0 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74  are.** used by t
326f0 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
32700 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46  on of SQLite.  F
32710 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
32720 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20  f SQLite.** may 
32730 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  add additional s
32740 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20  tatic mutexes.  
32750 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  Static mutexes a
32760 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  re for internal.
32770 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
32780 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
32790 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51  ions that use SQ
327a0 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f  Lite mutexes sho
327b0 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20  uld.** use only 
327c0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
327d0 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  xes returned by 
327e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
327f0 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  T or.** SQLITE_M
32800 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a  UTEX_RECURSIVE..
32810 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e  **.** {H17018} N
32820 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20  ote that if one 
32830 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  of the dynamic m
32840 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20  utex parameters 
32850 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
32860 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f  ST.** or SQLITE_
32870 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
32880 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71   is used then sq
32890 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
328a0 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  c().** returns a
328b0 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78   different mutex
328c0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20   on every call. 
328d0 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f   {H17034} But fo
328e0 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20  r the static.** 
328f0 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
32900 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
32910 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
32920 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
32930 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
32940 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  number..**.** {H
32950 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74  17019} The sqlit
32960 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20  e3_mutex_free() 
32970 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61  routine dealloca
32980 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79  tes a previously
32990 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79  .** allocated dy
329a0 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31  namic mutex. {H1
329b0 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20  7020} SQLite is 
329c0 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c  careful to deall
329d0 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64  ocate every.** d
329e0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61  ynamic mutex tha
329f0 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20  t it allocates. 
32a00 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e  {A17021} The dyn
32a10 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73  amic mutexes mus
32a20 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75  t not be in.** u
32a30 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  se when they are
32a40 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41   deallocated. {A
32a50 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e  17022} Attemptin
32a60 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  g to deallocate 
32a70 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65  a static.** mute
32a80 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  x results in und
32a90 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
32aa0 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65   {H17023} SQLite
32ab0 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74   never deallocat
32ac0 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d  es.** a static m
32ad0 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  utex. {END}.**.*
32ae0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
32af0 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20  tex_enter() and 
32b00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
32b10 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74  y() routines att
32b20 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72  empt.** to enter
32b30 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32   a mutex. {H1702
32b40 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  4} If another th
32b50 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
32b60 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
32b70 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
32b80 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
32b90 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
32ba0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
32bb0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
32bc0 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32  ITE_BUSY. {H1702
32bd0 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  5}  The sqlite3_
32be0 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65  mutex_try() inte
32bf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53  rface returns [S
32c00 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f  QLITE_OK].** upo
32c10 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74  n successful ent
32c20 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75  ry.  {H17026} Mu
32c30 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73  texes created us
32c40 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  ing.** SQLITE_MU
32c50 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
32c60 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c  n be entered mul
32c70 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74  tiple times by t
32c80 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a  he same thread..
32c90 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73  ** {H17027} In s
32ca0 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
32cb0 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
32cc0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
32cd0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
32ce0 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
32cf0 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
32d00 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66  er.  {A17028} If
32d10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32d20 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20   tries to enter 
32d30 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e  any other.** kin
32d40 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20  d of mutex more 
32d50 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62  than once, the b
32d60 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
32d70 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39  ined..** {H17029
32d80 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  } SQLite will ne
32d90 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73  ver exhibit.** s
32da0 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20  uch behavior in 
32db0 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d  its own use of m
32dc0 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f  utexes..**.** So
32dd0 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20  me systems (for 
32de0 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73  example, Windows
32df0 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70   95) do not supp
32e00 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ort the operatio
32e10 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64  n.** implemented
32e20 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   by sqlite3_mute
32e30 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f  x_try().  On tho
32e40 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69  se systems, sqli
32e50 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a  te3_mutex_try().
32e60 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  ** will always r
32e70 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53  eturn SQLITE_BUS
32e80 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65  Y.  {H17030} The
32e90 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
32ea0 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73  y ever uses.** s
32eb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
32ec0 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a  () as an optimiz
32ed0 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73  ation so this is
32ee0 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61   acceptable beha
32ef0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  vior..**.** {H17
32f00 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  031} The sqlite3
32f10 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72  _mutex_leave() r
32f20 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d  outine exits a m
32f30 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a  utex that was.**
32f40 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65   previously ente
32f50 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20  red by the same 
32f60 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32  thread.  {A17032
32f70 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  } The behavior.*
32f80 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
32f90 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
32fa0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
32fb0 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
32fc0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
32fd0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
32fe0 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48  y allocated.  {H
32ff0 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69  17033} SQLite wi
33000 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
33010 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ither. {END}.**.
33020 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  ** If the argume
33030 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
33040 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c  tex_enter(), sql
33050 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
33060 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  , or.** sqlite3_
33070 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73  mutex_leave() is
33080 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
33090 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20   then all three 
330a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61  routines.** beha
330b0 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ve as no-ops..**
330c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
330d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
330e0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
330f0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
33100 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
33110 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
33120 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
33130 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
33140 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
33150 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
33160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
33170 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
33180 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
33190 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
331a0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
331b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
331c0 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
331d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
331e0 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f  REF: Mutex Metho
331f0 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32  ds Object {H1712
33200 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45  0} <S20130>.** E
33210 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
33220 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
33230 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
33240 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d  defines the low-
33250 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a  level routines.*
33260 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61  * used to alloca
33270 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78  te and use mutex
33280 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c  es..**.** Usuall
33290 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  y, the default m
332a0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
332b0 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79  ions provided by
332c0 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73   SQLite are.** s
332d0 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76  ufficient, howev
332e0 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20  er the user has 
332f0 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75  the option of su
33300 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73  bstituting a cus
33310 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tom.** implement
33320 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61  ation for specia
33330 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74  lized deployment
33340 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72  s or systems for
33350 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a   which SQLite.**
33360 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64   does not provid
33370 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  e a suitable imp
33380 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20  lementation. In 
33390 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75  this case, the u
333a0 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61  ser.** creates a
333b0 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20  nd populates an 
333c0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
333d0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61   structure to pa
333e0 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ss.** to sqlite3
333f0 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20  _config() along 
33400 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
33410 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f  _CONFIG_MUTEX] o
33420 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69  ption..** Additi
33430 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61  onally, an insta
33440 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
33450 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  cture can be use
33460 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75  d as an.** outpu
33470 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20  t variable when 
33480 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73  querying the sys
33490 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72  tem for the curr
334a0 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ent mutex.** imp
334b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69  lementation, usi
334c0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
334d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20  ONFIG_GETMUTEX] 
334e0 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  option..**.** Th
334f0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
33500 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
33510 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
33520 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
33530 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e  art of system in
33540 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20  itialization by 
33550 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  the sqlite3_init
33560 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  ialize() functio
33570 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54  n..** {H17001} T
33580 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f  he xMutexInit ro
33590 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63  utine shall be c
335a0 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20  alled by SQLite 
335b0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a  once for each.**
335c0 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
335d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  to [sqlite3_init
335e0 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ialize()]..**.**
335f0 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d   The xMutexEnd m
33600 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79  ethod defined by
33610 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
33620 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a  is invoked as.**
33630 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20   part of system 
33640 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20  shutdown by the 
33650 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
33660 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  () function. The
33670 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
33680 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f  on of this metho
33690 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f  d is expected to
336a0 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74   release all out
336b0 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f  standing.** reso
336c0 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62  urces obtained b
336d0 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68  y the mutex meth
336e0 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ods implementati
336f0 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a  on, especially.*
33700 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64  * those obtained
33710 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e   by the xMutexIn
33720 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30  it method. {H170
33730 30 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e  03} The xMutexEn
33740 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
33750 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65   shall be invoke
33760 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33770 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33780 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
33790 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
337a0 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20  g seven methods 
337b0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
337c0 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65  structure (xMute
337d0 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65  xAlloc,.** xMute
337e0 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74  xFree, xMutexEnt
337f0 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78  er, xMutexTry, x
33800 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74  MutexLeave, xMut
33810 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d  exHeld and.** xM
33820 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70  utexNotheld) imp
33830 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f  lement the follo
33840 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20  wing interfaces 
33850 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a  (respectively):.
33860 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
33870 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
33880 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f  utex_alloc()] </
33890 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
338a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
338b0 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ee()] </li>.**  
338c0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
338d0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c  mutex_enter()] <
338e0 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
338f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74  [sqlite3_mutex_t
33900 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ry()] </li>.**  
33910 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
33920 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c  mutex_leave()] <
33930 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
33940 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68  [sqlite3_mutex_h
33950 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  eld()] </li>.** 
33960 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
33970 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
33980 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ] </li>.** </ul>
33990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20  .**.** The only 
339a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68  difference is th
339b0 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71  at the public sq
339c0 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69  lite3_XXX functi
339d0 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a  ons enumerated.*
339e0 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79  * above silently
339f0 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f   ignore any invo
33a00 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73  cations that pas
33a10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33a20 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
33a30 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
33a40 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  dle. The impleme
33a50 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
33a60 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a  methods defined.
33a70 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ** by this struc
33a80 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71  ture are not req
33a90 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  uired to handle 
33aa0 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72  this case, the r
33ab0 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73  esults.** of pas
33ac0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
33ad0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
33ae0 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
33af0 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65  dle are undefine
33b00 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73  d.** (i.e. it is
33b10 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70   acceptable to p
33b20 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d  rovide an implem
33b30 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65  entation that se
33b40 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74  gfaults if.** it
33b50 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c   is passed a NUL
33b60 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74  L pointer)..*/.t
33b70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
33b80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
33b90 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ods sqlite3_mute
33ba0 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  x_methods;.struc
33bb0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
33bc0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
33bd0 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f  (*xMutexInit)(vo
33be0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  id);.  int (*xMu
33bf0 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20  texEnd)(void);. 
33c00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a   sqlite3_mutex *
33c10 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69  (*xMutexAlloc)(i
33c20 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
33c30 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65  utexFree)(sqlite
33c40 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
33c50 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72  id (*xMutexEnter
33c60 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
33c70 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
33c80 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d  exTry)(sqlite3_m
33c90 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
33ca0 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73  (*xMutexLeave)(s
33cb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
33cc0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48  .  int (*xMutexH
33cd0 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
33ce0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
33cf0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71  MutexNotheld)(sq
33d00 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
33d10 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33d20 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69  EF: Mutex Verifi
33d30 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20  cation Routines 
33d40 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30  {H17080} <S20130
33d50 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  > <S30800>.**.**
33d60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
33d70 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
33d80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
33d90 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
33da0 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
33db0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
33dc0 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
33dd0 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20  s. {H17081} The 
33de0 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e  SQLite core.** n
33df0 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20  ever uses these 
33e00 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20  routines except 
33e10 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74  inside an assert
33e20 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69  () and applicati
33e30 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73  ons.** are advis
33e40 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65  ed to follow the
33e50 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72   lead of the cor
33e60 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65  e.  {H17082} The
33e70 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72   core only.** pr
33e80 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74  ovides implement
33e90 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65  ations for these
33ea0 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69   routines when i
33eb0 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  t is compiled.**
33ec0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
33ed0 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41  _DEBUG flag.  {A
33ee0 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20  17087} External 
33ef0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
33f00 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
33f10 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
33f20 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
33f30 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
33f40 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
33f50 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
33f60 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
33f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20  .**.** {H17083} 
33f80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73  These routines s
33f90 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75  hould return tru
33fa0 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69  e if the mutex i
33fb0 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74  n their argument
33fc0 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e  .** is held or n
33fd0 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74  ot held, respect
33fe0 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61  ively, by the ca
33ff0 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a  lling thread..**
34000 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65  .** {X17084} The
34010 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34020 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  is not required 
34030 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73  to provided vers
34040 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ions of these.**
34050 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61   routines that a
34060 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66  ctually work. If
34070 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
34080 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  ion does not pro
34090 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20  vide working.** 
340a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
340b0 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73  e routines, it s
340c0 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70  hould at least p
340d0 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61  rovide stubs tha
340e0 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75  t always.** retu
340f0 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20  rn true so that 
34100 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74  one does not get
34110 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74   spurious assert
34120 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a  ion failures..**
34130 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20  .** {H17085} If 
34140 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
34150 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
34160 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ld() is a NULL p
34170 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74  ointer then.** t
34180 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  he routine shoul
34190 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e  d return 1.  {EN
341a0 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f  D} This seems co
341b0 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20  unter-intuitive 
341c0 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79  since.** clearly
341d0 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f   the mutex canno
341e0 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20  t be held if it 
341f0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20  does not exist. 
34200 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20   But the.** the 
34210 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78  reason the mutex
34220 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
34230 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62  is because the b
34240 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75  uild is not.** u
34250 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41  sing mutexes.  A
34260 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e  nd we do not wan
34270 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63  t the assert() c
34280 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
34290 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
342a0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f  _mutex_held() to
342b0 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d   fail, so a non-
342c0 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a  zero return is.*
342d0 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  * the appropriat
342e0 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20  e thing to do.  
342f0 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c  {H17086} The sql
34300 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
34310 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ld().** interfac
34320 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65  e should also re
34330 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65  turn 1 when give
34340 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
34350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34360 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69  _mutex_held(sqli
34370 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
34380 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
34390 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  otheld(sqlite3_m
343a0 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
343b0 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54  API3REF: Mutex T
343c0 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48  ypes {H17001} <H
343d0 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  17000>.**.** The
343e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
343f0 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61  alloc()] interfa
34400 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  ce takes a singl
34410 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68  e argument.** wh
34420 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ich is one of th
34430 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
34440 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tants..**.** The
34450 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d   set of static m
34460 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67  utexes may chang
34470 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74  e from one SQLit
34480 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
34490 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
344a0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65  cations that ove
344b0 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d  rride the built-
344c0 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d  in mutex logic m
344d0 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72  ust be.** prepar
344e0 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74  ed to accommodat
344f0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  e additional sta
34500 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a  tic mutexes..*/.
34510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
34520 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20  UTEX_FAST       
34530 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
34540 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
34550 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a  URSIVE        1.
34560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
34570 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
34580 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  ER    2.#define 
34590 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
345a0 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20  TIC_MEM       3 
345b0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   /* sqlite3_mall
345c0 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oc() */.#define 
345d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
345e0 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20  TIC_MEM2      4 
345f0 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a   /* NOT USED */.
34600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
34610 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e  UTEX_STATIC_OPEN
34620 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
34630 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a  te3BtreeOpen() *
34640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34650 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
34660 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71  NG      5  /* sq
34670 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a  lite3_random() *
34680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34690 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
346a0 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72  U       6  /* lr
346b0 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23  u page list */.#
346c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
346d0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20  TEX_STATIC_LRU2 
346e0 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70       7  /* lru p
346f0 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a  age list */../*.
34700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
34710 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20  rieve the mutex 
34720 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
34730 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30  onnection {H1700
34740 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a  2} <H17000>.**.*
34750 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
34760 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34770 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  er the [sqlite3_
34780 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68  mutex] object th
34790 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65  at .** serialize
347a0 73 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20  s access to the 
347b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
347c0 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74  tion] given in t
347d0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  he argument.** w
347e0 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69  hen the [threadi
347f0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69  ng mode] is Seri
34800 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68  alized..** If th
34810 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
34820 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72  e] is Single-thr
34830 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72  ead or Multi-thr
34840 65 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a  ead then this.**
34850 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34860 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
34870 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
34880 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  x *sqlite3_db_mu
34890 74 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  tex(sqlite3*);..
348a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
348b0 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f  Low-Level Contro
348c0 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69  l Of Database Fi
348d0 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33  les {H11300} <S3
348e0 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  0800>.**.** {H11
348f0 33 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  301} The [sqlite
34900 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
34910 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ] interface make
34920 73 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20  s a direct call 
34930 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43  to the.** xFileC
34940 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f  ontrol method fo
34950 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  r the [sqlite3_i
34960 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
34970 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  t associated.** 
34980 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
34990 72 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74  r database ident
349a0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
349b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48  ond argument. {H
349c0 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61  11302} The.** na
349d0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
349e0 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61  se is the name a
349f0 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64  ssigned to the d
34a00 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a  atabase by the.*
34a10 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  * <a href="lang_
34a20 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54  attach.html">ATT
34a30 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d  ACH</a> SQL comm
34a40 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20  and that opened 
34a50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
34a60 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e   {H11303} To con
34a70 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61  trol the main da
34a80 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65  tabase file, use
34a90 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
34aa0 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  .** or a NULL po
34ab0 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20  inter. {H11304} 
34ac0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
34ad0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
34ae0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
34af0 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
34b00 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
34b10 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
34b20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34b30 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
34b40 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
34b50 20 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72    {H11305} The r
34b60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
34b70 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a  he xFileControl.
34b80 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65  ** method become
34b90 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34ba0 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
34bb0 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  ne..**.** {H1130
34bc0 36 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  6} If the second
34bd0 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e   parameter (zDbN
34be0 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61  ame) does not ma
34bf0 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  tch the name of 
34c00 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61  any.** open data
34c10 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20  base file, then 
34c20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20  SQLITE_ERROR is 
34c30 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30  returned. {H1130
34c40 37 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a  7} This error.**
34c50 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d   code is not rem
34c60 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c  embered and will
34c70 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64   not be recalled
34c80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
34c90 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  code()].** or [s
34ca0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
34cb0 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75  . {A11308} The u
34cc0 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43  nderlying xFileC
34cd0 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69  ontrol method mi
34ce0 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75  ght.** also retu
34cf0 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  rn SQLITE_ERROR.
34d00 20 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65    {A11309} There
34d10 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69   is no way to di
34d20 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65  stinguish betwee
34d30 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63  n.** an incorrec
34d40 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e  t zDbName and an
34d50 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65   SQLITE_ERROR re
34d60 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e  turn from the un
34d70 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c  derlying.** xFil
34d80 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
34d90 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65   {END}.**.** See
34da0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46   also: [SQLITE_F
34db0 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a  CNTL_LOCKSTATE].
34dc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
34dd0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69  ile_control(sqli
34de0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
34df0 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f   *zDbName, int o
34e00 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  p, void*);../*.*
34e10 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
34e20 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48  ing Interface {H
34e30 31 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11400} <S30800>.
34e40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34e50 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29  3_test_control()
34e60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
34e70 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69  ed to read out i
34e80 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65  nternal.** state
34e90 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74   of SQLite and t
34ea0 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20  o inject faults 
34eb0 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20  into SQLite for 
34ec0 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f  testing.** purpo
34ed0 73 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  ses.  The first 
34ee0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
34ef0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74  operation code t
34f00 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
34f10 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65  * the number, me
34f20 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61  aning, and opera
34f30 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73  tion of all subs
34f40 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
34f50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
34f60 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66  terface is not f
34f70 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63  or use by applic
34f80 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73  ations.  It exis
34f90 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72  ts solely.** for
34fa0 20 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63   verifying the c
34fb0 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e  orrect operation
34fc0 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
34fd0 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69  ibrary.  Dependi
34fe0 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65  ng.** on how the
34ff0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
35000 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69  is compiled, thi
35010 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  s interface migh
35020 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a  t not exist..**.
35030 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
35040 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  f the operation 
35050 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61  codes, their mea
35060 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d  nings, the param
35070 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61  eters.** they ta
35080 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65  ke, and what the
35090 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62  y do are all sub
350a0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
350b0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a  ithout notice..*
350c0 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66  * Unlike most of
350d0 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c   the SQLite API,
350e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
350f0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
35100 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63   to.** operate c
35110 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d  onsistently from
35120 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
35130 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74  the next..*/.int
35140 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f   sqlite3_test_co
35150 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e  ntrol(int op, ..
35160 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35170 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74  REF: Testing Int
35180 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e  erface Operation
35190 20 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20   Codes {H11410} 
351a0 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H11400>.**.** T
351b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
351c0 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65  re the valid ope
351d0 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61  ration code para
351e0 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61  meters used.** a
351f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35200 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
35210 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _test_control()]
35220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61  ..**.** These pa
35230 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65  rameters and the
35240 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20  ir meanings are 
35250 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
35260 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74  e.** without not
35270 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75  ice.  These valu
35280 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69  es are for testi
35290 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79  ng purposes only
352a0 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
352b0 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  s should not use
352c0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61   any of these pa
352d0 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a  rameters or the.
352e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  ** [sqlite3_test
352f0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
35300 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
35310 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
35320 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20  L_PRNG_SAVE     
35330 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
35340 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
35350 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52  CTRL_PRNG_RESTOR
35360 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a  E             6.
35370 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
35380 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53  ESTCTRL_PRNG_RES
35390 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ET              
353a0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
353b0 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45  E_TESTCTRL_BITVE
353c0 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20  C_TEST          
353d0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
353e0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41  LITE_TESTCTRL_FA
353f0 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20  ULT_INSTALL     
35400 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
35410 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
35420 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48  _BENIGN_MALLOC_H
35430 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66  OOKS     10.#def
35440 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
35450 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45  TRL_PENDING_BYTE
35460 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a              11..
35470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35480 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53  SQLite Runtime S
35490 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c  tatus {H17200} <
354a0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60200>.** EXPER
354b0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
354c0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
354d0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
354e0 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20   runtime status 
354f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
35500 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d  bout the preform
35510 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20  ance of SQLite, 
35520 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74  and optionally t
35530 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a  o reset various.
35540 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  ** highwater mar
35550 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  ks.  The first a
35560 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
35570 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a  teger code for.*
35580 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 70  * the specific p
35590 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73  arameter to meas
355a0 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64  ure.  Recognized
355b0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a   integer codes.*
355c0 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  * are of the for
355d0 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53  m [SQLITE_STATUS
355e0 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53  _MEMORY_USED | S
355f0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e  QLITE_STATUS_...
35600 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  ]..** The curren
35610 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  t value of the p
35620 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 75  arameter is retu
35630 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72  rned into *pCurr
35640 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68  ent..** The high
35650 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c  est recorded val
35660 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ue is returned i
35670 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20  n *pHighwater.  
35680 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46  If the.** resetF
35690 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 65  lag is true, the
356a0 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 65  n the highest re
356b0 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 65  cord value is re
356c0 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48  set after.** *pH
356d0 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 74  ighwater is writ
356e0 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65  ten. Some parame
356f0 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f  ters do not reco
35700 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a  rd the highest.*
35710 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
35720 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ose parameters.*
35730 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  * nothing is wri
35740 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68  tten into *pHigh
35750 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65  water and the re
35760 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72  setFlag is ignor
35770 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72  ed..** Other par
35780 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f  ameters record o
35790 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 65  nly the highwate
357a0 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74  r mark and not t
357b0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61  he current.** va
357c0 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20  lue.  For these 
357d0 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 72  latter parameter
357e0 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  s nothing is wri
357f0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72  tten into *pCurr
35800 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ent..**.** This 
35810 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35820 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63  SQLITE_OK on suc
35830 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a  cess and a non-z
35840 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  ero.** [error co
35850 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
35860 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35870 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ne is threadsafe
35880 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d   but is not atom
35890 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ic.  This routin
358a0 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20  e can.** called 
358b0 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65  while other thre
358c0 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20  ads are running 
358d0 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66  the same or diff
358e0 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20  erent SQLite.** 
358f0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
35900 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20  ever the values 
35910 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75  returned in *pCu
35920 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48  rrent and.** *pH
35930 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74  ighwater reflect
35940 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53   the status of S
35950 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65  QLite at differe
35960 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d  nt points in tim
35970 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70  e.** and it is p
35980 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f  ossible that ano
35990 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68  ther thread migh
359a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72  t change the par
359b0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74  ameter.** in bet
359c0 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77  ween the times w
359d0 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e  hen *pCurrent an
359e0 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72  d *pHighwater ar
359f0 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  e written..**.**
35a00 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
35a10 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d  te3_db_status()]
35a20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
35a30 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
35a40 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f  te3_status(int o
35a50 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74  p, int *pCurrent
35a60 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65  , int *pHighwate
35a70 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67  r, int resetFlag
35a80 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
35a90 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61  REF: Status Para
35aa0 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20  meters {H17250} 
35ab0 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <H17200>.** EXPE
35ac0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
35ad0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
35ae0 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65  stants designate
35af0 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d   various run-tim
35b00 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74  e status paramet
35b10 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ers.** that can 
35b20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  be returned by [
35b30 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
35b40 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
35b50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54   <dt>SQLITE_STAT
35b60 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f  US_MEMORY_USED</
35b70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
35b80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
35b90 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20   current amount 
35ba0 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65  of memory checke
35bb0 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  d out.** using [
35bc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35bd0 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 74  ], either direct
35be0 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79  ly or indirectly
35bf0 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65  .  The.** figure
35c00 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20   includes calls 
35c10 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33  made to [sqlite3
35c20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68  _malloc()] by th
35c30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
35c40 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65   and internal me
35c50 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 68  mory usage by th
35c60 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
35c70 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72  .  Scratch memor
35c80 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  y.** controlled 
35c90 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
35ca0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61  G_SCRATCH] and a
35cb0 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61  uxiliary page-ca
35cc0 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f  che.** memory co
35cd0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c  ntrolled by [SQL
35ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
35cf0 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63  ACHE] is not inc
35d00 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73  luded in.** this
35d10 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
35d20 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64   amount returned
35d30 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74   is the sum of t
35d40 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
35d50 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74   sizes as report
35d60 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 20  ed by the xSize 
35d70 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74  method in [sqlit
35d80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e  e3_mem_methods].
35d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
35da0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41  SQLITE_STATUS_MA
35db0 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  LLOC_SIZE</dt>.*
35dc0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
35dd0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
35de0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
35df0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
35e00 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
35e10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
35e20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
35e30 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68  ealloc()] (or th
35e40 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  eir.** internal 
35e50 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f  equivalents).  O
35e60 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
35e70 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
35e80 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
35e90 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
35ea0 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
35eb0 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
35ec0 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
35ed0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
35ee0 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
35ef0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
35f00 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
35f10 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
35f20 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a  CACHE_USED</dt>.
35f30 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
35f40 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
35f50 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
35f60 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68  s used out of th
35f70 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20  e.** [pagecache 
35f80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
35f90 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69  ] that was confi
35fa0 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20  gured using .** 
35fb0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
35fc0 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a  AGECACHE].  The.
35fd0 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ** value returne
35fe0 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e  d is in pages, n
35ff0 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  ot in bytes.</dd
36000 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36010 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
36020 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  CHE_OVERFLOW</dt
36030 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36040 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
36050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
36060 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 68  tes of page cach
36070 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e.** allocation 
36080 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20  which could not 
36090 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79  be statisfied by
360a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
360b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a  FIG_PAGECACHE].*
360c0 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65  * buffer and whe
360d0 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65  re forced to ove
360e0 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65  rflow to [sqlite
360f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
36100 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61  e.** returned va
36110 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  lue includes all
36120 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ocations that ov
36130 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65  erflowed because
36140 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74   they.** where t
36150 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 77  oo large (they w
36160 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  ere larger than 
36170 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74  the "sz" paramet
36180 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
36190 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
361a0 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69  E]) and allocati
361b0 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f  ons that overflo
361c0 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e  wed because.** n
361d0 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 74  o space was left
361e0 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
361f0 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  he.</dd>.**.** <
36200 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
36210 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c  _PAGECACHE_SIZE<
36220 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
36230 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72   parameter recor
36240 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d  ds the largest m
36250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
36260 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64   request.** hand
36270 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65  ed to [pagecache
36280 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
36290 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61  r].  Only the va
362a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
362b0 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  the.** *pHighwat
362c0 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  er parameter to 
362d0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
362e0 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73  )] is of interes
362f0 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75  t.  .** The valu
36300 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  e written into t
36310 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72  he *pCurrent par
36320 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69  ameter is undefi
36330 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
36340 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
36350 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f  S_SCRATCH_USED</
36360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
36370 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e  parameter return
36380 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
36390 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64  allocations used
363a0 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   out of the.** [
363b0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61  scratch memory a
363c0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
363d0 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53  ured using.** [S
363e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
363f0 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75  ATCH].  The valu
36400 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e  e returned is in
36410 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f   allocations, no
36420 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20  t.** in bytes.  
36430 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74  Since a single t
36440 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68  hread may only h
36450 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20  ave one scratch 
36460 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75  allocation.** ou
36470 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d  tstanding at tim
36480 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  e, this paramete
36490 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74  r also reports t
364a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  he number of thr
364b0 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63  eads.** using sc
364c0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20  ratch memory at 
364d0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f  the same time.</
364e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
364f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
36500 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74  TCH_OVERFLOW</dt
36510 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36520 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
36530 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
36540 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d  tes of scratch m
36550 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36560 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20  ion which could 
36570 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65  not be statisfie
36580 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
36590 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
365a0 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77  .** buffer and w
365b0 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f  here forced to o
365c0 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69  verflow to [sqli
365d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
365e0 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65  The values.** re
365f0 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f  turned include o
36600 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65  verflows because
36610 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 61   the requested a
36620 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f  llocation was to
36630 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61  o.** larger (tha
36640 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68  t is, because th
36650 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f  e requested allo
36660 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65  cation was large
36670 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73  r than the.** "s
36680 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  z" parameter to 
36690 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
366a0 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63  CRATCH]) and bec
366b0 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20  ause no scratch 
366c0 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20  buffer.** slots 
366d0 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a  were available..
366e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
366f0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
36700 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64  _SCRATCH_SIZE</d
36710 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
36720 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73  arameter records
36730 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d   the largest mem
36740 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
36750 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64  equest.** handed
36760 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d   to [scratch mem
36770 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20  ory allocator]. 
36780 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20   Only the value 
36790 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a  returned in the.
367a0 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70  ** *pHighwater p
367b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
367c0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69  ite3_status()] i
367d0 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20  s of interest.  
367e0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72  .** The value wr
367f0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a  itten into the *
36800 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74  pCurrent paramet
36810 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  er is undefined.
36820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
36830 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
36840 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a  RSER_STACK</dt>.
36850 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
36860 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68  meter records th
36870 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 72  e deepest parser
36880 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f   stack.  It is o
36890 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75  nly.** meaningfu
368a0 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  l if SQLite is c
368b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59  ompiled with [YY
368c0 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50  TRACKMAXSTACKDEP
368d0 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  TH].</dd>.** </d
368e0 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61  l>.**.** New sta
368f0 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d  tus parameters m
36900 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d  ay be added from
36910 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a   time to time..*
36920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36930 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55  _STATUS_MEMORY_U
36940 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a 23  SED          0.#
36950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
36960 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55  ATUS_PAGECACHE_U
36970 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 66  SED       1.#def
36980 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
36990 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52  S_PAGECACHE_OVER
369a0 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65  FLOW   2.#define
369b0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53   SQLITE_STATUS_S
369c0 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 20  CRATCH_USED     
369d0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
369e0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
369f0 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20  TCH_OVERFLOW    
36a00 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
36a10 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f  E_STATUS_MALLOC_
36a20 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a  SIZE          5.
36a30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
36a40 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41  TATUS_PARSER_STA
36a50 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 65  CK         6.#de
36a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
36a70 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a  US_PAGECACHE_SIZ
36a80 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e  E       7.#defin
36a90 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
36aa0 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20  SCRATCH_SIZE    
36ab0 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41       8../*.** CA
36ac0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
36ad0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74   Connection Stat
36ae0 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30  us {H17500} <S60
36af0 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
36b00 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
36b10 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
36b20 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75  d to retrieve ru
36b30 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66  ntime status inf
36b40 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f  ormation .** abo
36b50 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74  ut a single [dat
36b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36b70 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
36b80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
36b90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36ba0 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62  tion object to b
36bb0 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  e interrogated. 
36bc0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
36bd0 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70  ment.** is the p
36be0 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65  arameter to inte
36bf0 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e  rrogate.  Curren
36c00 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c  tly, the only al
36c10 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66  lowed value.** f
36c20 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  or the second pa
36c30 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49  rameter is [SQLI
36c40 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b  TE_DBSTATUS_LOOK
36c50 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20  ASIDE_USED]..** 
36c60 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f  Additional optio
36c70 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61  ns will likely a
36c80 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 20  ppear in future 
36c90 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
36ca0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75  te..**.** The cu
36cb0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74  rrent value of t
36cc0 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 72  he requested par
36cd0 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 65  ameter is writte
36ce0 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20  n into *pCur.** 
36cf0 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 20  and the highest 
36d00 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61  instantaneous va
36d10 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  lue is written i
36d20 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66  nto *pHiwtr.  If
36d30 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67  .** the resetFlg
36d40 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
36d50 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61  he highest insta
36d60 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69  ntaneous value i
36d70 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20  s.** reset back 
36d80 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72  down to the curr
36d90 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ent value..**.**
36da0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36db0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e  te3_status()] an
36dc0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  d [sqlite3_stmt_
36dd0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51  status()]..*/.SQ
36de0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
36df0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  L int sqlite3_db
36e00 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a  _status(sqlite3*
36e10 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70  , int op, int *p
36e20 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72  Cur, int *pHiwtr
36e30 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b  , int resetFlg);
36e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36e50 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74  : Status Paramet
36e60 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65  ers for database
36e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31   connections {H1
36e80 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a  7520} <H17500>.*
36e90 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
36ea0 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62  *.** Status verb
36eb0 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64  s for [sqlite3_d
36ec0 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a  b_status()]..**.
36ed0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
36ee0 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c  QLITE_DBSTATUS_L
36ef0 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64  OOKASIDE_USED</d
36f00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
36f10 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73  arameter returns
36f20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c   the number of l
36f30 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
36f40 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a  slots currently.
36f50 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c  ** checked out.<
36f60 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
36f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36f80 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49  DBSTATUS_LOOKASI
36f90 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a  DE_USED     0...
36fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36fb0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
36fc0 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 35  nt Status {H1755
36fd0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45  0} <S60200>.** E
36fe0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
36ff0 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 20  * Each prepared 
37000 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61  statement mainta
37010 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b  ins various.** [
37020 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55  SQLITE_STMTSTATU
37030 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72  S_SORT | counter
37040 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 20  s] that measure 
37050 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
37060 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 65   times it has pe
37070 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63  rformed specific
37080 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68   operations.  Th
37090 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e  ese counters can
370a0 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d  .** be used to m
370b0 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f  onitor the perfo
370c0 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 72  rmance character
370d0 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 72  istics of the pr
370e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
370f0 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  ents.  For examp
37100 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65  le, if the numbe
37110 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73  r of table steps
37120 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 73   greatly exceeds
37130 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
37140 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 73  f table searches
37150 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c   or result rows,
37160 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64   that would tend
37170 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20   to indicate.** 
37180 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
37190 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75  d statement is u
371a0 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c  sing a full tabl
371b0 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 68  e scan rather th
371c0 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20  an.** an index. 
371d0 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74   .**.** This int
371e0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
371f0 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 72  o retrieve and r
37200 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c  eset counter val
37210 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70  ues from.** a [p
37220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37230 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  t].  The first a
37240 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70  rgument is the p
37250 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37260 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62  t.** object to b
37270 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  e interrogated. 
37280 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
37290 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  ment.** is an in
372a0 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61  teger code for a
372b0 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54   specific [SQLIT
372c0 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52  E_STMTSTATUS_SOR
372d0 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20  T | counter].** 
372e0 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74  to be interrogat
372f0 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72  ed. .** The curr
37300 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ent value of the
37310 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74   requested count
37320 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
37330 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 46  ** If the resetF
37340 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  lg is true, then
37350 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20   the counter is 
37360 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66  reset to zero af
37370 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  ter this.** inte
37380 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72  rface call retur
37390 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ns..**.** See al
373a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  so: [sqlite3_sta
373b0 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tus()] and [sqli
373c0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d  te3_db_status()]
373d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
373e0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
373f0 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73  ite3_stmt_status
37400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
37410 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74  int op,int reset
37420 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Flg);../*.** CAP
37430 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61  I3REF: Status Pa
37440 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65  rameters for pre
37450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
37460 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35   {H17570} <H1755
37470 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
37480 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70  AL.**.** These p
37490 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
374a0 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  os define intege
374b0 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d  r codes that nam
374c0 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c  e counter.** val
374d0 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ues associated w
374e0 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
374f0 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20  _stmt_status()] 
37500 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68  interface..** Th
37510 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
37520 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65  e various counte
37530 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77  rs are as follow
37540 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
37550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54   <dt>SQLITE_STMT
37560 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f  STATUS_FULLSCAN_
37570 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STEP</dt>.** <dd
37580 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d  >This is the num
37590 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
375a0 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65  t SQLite has ste
375b0 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a  pped forward in.
375c0 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61  ** a table as pa
375d0 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62  rt of a full tab
375e0 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20  le scan.  Large 
375f0 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73  numbers for this
37600 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20   counter.** may 
37610 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75  indicate opportu
37620 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f  nities for perfo
37630 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65  rmance improveme
37640 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63  nt through .** c
37650 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e  areful use of in
37660 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  dices.</dd>.**.*
37670 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d  * <dt>SQLITE_STM
37680 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74  TSTATUS_SORT</dt
37690 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73  >.** <dd>This is
376a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73   the number of s
376b0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74  ort operations t
376c0 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65  hat have occurre
376d0 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f  d..** A non-zero
376e0 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63   value in this c
376f0 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63  ounter may indic
37700 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ate an opportuni
37710 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65  ty to.** improve
37720 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65  ment performance
37730 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c   through careful
37740 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e   use of indices.
37750 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
37760 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
37770 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46  ITE_STMTSTATUS_F
37780 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20  ULLSCAN_STEP    
37790 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
377a0 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52  E_STMTSTATUS_SOR
377b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  T              2
377c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
377d0 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61  : Custom Page Ca
377e0 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58  che Object.** EX
377f0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
37800 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61   The sqlite3_pca
37810 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71  che type is opaq
37820 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65  ue.  It is imple
37830 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65  mented by.** the
37840 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c   pluggable modul
37850 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  e.  The SQLite c
37860 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c  ore has no knowl
37870 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73  edge of.** its s
37880 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20  ize or internal 
37890 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65  structure and ne
378a0 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74  ver deals with t
378b0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63  he.** sqlite3_pc
378c0 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65  ache object exce
378d0 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e  pt by holding an
378e0 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65  d passing pointe
378f0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a  rs.** to the obj
37900 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b  ect..**.** See [
37910 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
37920 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69  ethods] for addi
37930 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
37940 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
37950 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63  truct sqlite3_pc
37960 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61  ache sqlite3_pca
37970 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  che;../*.** CAPI
37980 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f  3REF: Applicatio
37990 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43  n Defined Page C
379a0 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d  ache..** EXPERIM
379b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
379c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
379d0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
379e0 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e  PCACHE], ...) in
379f0 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72  terface can.** r
37a00 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72  egister an alter
37a10 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68  native page cach
37a20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37a30 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
37a40 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  n .** instance o
37a50 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63  f the sqlite3_pc
37a60 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72  ache_methods str
37a70 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f  ucture. The majo
37a80 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20  rity of the .** 
37a90 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64  heap memory used
37aa0 20 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73   by sqlite is us
37ab0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
37ac0 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61  ache to cache da
37ad0 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d  ta read .** from
37ae0 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65  , or ready to be
37af0 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65   written to, the
37b00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
37b10 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20  By implementing 
37b20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67  a .** custom pag
37b30 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68  e cache using th
37b40 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69  is API, an appli
37b50 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72  cation can contr
37b60 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63  ol more .** prec
37b70 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74  isely the amount
37b80 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75   of memory consu
37b90 6d 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74  med by sqlite, t
37ba0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
37bb0 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20  .** said memory 
37bc0 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64  is allocated and
37bd0 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74   released, and t
37be0 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64  he policies used
37bf0 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   to .** determin
37c00 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20  e exactly which 
37c10 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62  parts of a datab
37c20 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63  ase file are cac
37c30 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20  hed and for .** 
37c40 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20  how long..**.** 
37c50 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  The contents of 
37c60 74 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72  the structure ar
37c70 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69  e copied to an i
37c80 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62  nternal buffer b
37c90 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68  y sqlite.** with
37ca0 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b  in the call to [
37cb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e  sqlite3_config].
37cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
37cd0 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c  () method is cal
37ce0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
37cf0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
37d00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
37d10 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c  .** (usually onl
37d20 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68  y once during th
37d30 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
37d40 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69  e process). It i
37d50 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f  s passed.** a co
37d60 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  py of the sqlite
37d70 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
37d80 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20  .pArg value. It 
37d90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
37da0 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20  et.** up global 
37db0 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d  structures and m
37dc0 75 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20  utexes required 
37dd0 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61  by the custom pa
37de0 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70  ge cache .** imp
37df0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65  lementation. The
37e00 20 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74   xShutdown() met
37e10 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72  hod is called fr
37e20 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73  om within .** [s
37e30 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
37e40 29 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69  )], if the appli
37e50 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74  cation invokes t
37e60 68 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20  his API. It can 
37e70 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c  be used.** to cl
37e80 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74  ean up any outst
37e90 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73  anding resources
37ea0 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20   before process 
37eb0 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71  shutdown, if req
37ec0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
37ed0 20 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f   xCreate() metho
37ee0 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  d is used to con
37ef0 73 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63  struct a new cac
37f00 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65  he instance. The
37f10 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
37f20 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20  ter, szPage, is 
37f30 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
37f40 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74  s of the pages t
37f50 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  hat must.** be a
37f60 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20  llocated by the 
37f70 63 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69  cache. szPage wi
37f80 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65  ll not be a powe
37f90 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a  r of two. The.**
37fa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37fb0 2c 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73  , bPurgeable, is
37fc0 20 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63   true if the cac
37fd0 68 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  he being created
37fe0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64   will.** be used
37ff0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
38000 73 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72  se pages read fr
38010 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64  om a file stored
38020 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20   on disk, or.** 
38030 66 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75  false if it is u
38040 73 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65  sed for an in-me
38050 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54  mory database. T
38060 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  he cache impleme
38070 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  ntation.** does 
38080 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61  not have to do a
38090 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20  nything special 
380a0 62 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c  based on the val
380b0 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65  ue of bPurgeable
380c0 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c  ,.** it is purel
380d0 79 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a  y advisory. .**.
380e0 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a  ** The xCachesiz
380f0 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62  e() method may b
38100 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
38110 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74  time by SQLite t
38120 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67  o set the.** sug
38130 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63  gested maximum c
38140 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65  ache-size (numbe
38150 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65  r of pages store
38160 64 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a  d by) the cache.
38170 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73  ** instance pass
38180 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
38190 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69  argument. This i
381a0 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66  s the value conf
381b0 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20  igured using.** 
381c0 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41  the SQLite "[PRA
381d0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22  GMA cache_size]"
381e0 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74   command. As wit
381f0 68 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65  h the bPurgeable
38200 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74   parameter,.** t
38210 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
38220 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
38230 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67  d to do anything
38240 20 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68   special with th
38250 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20  is.** value, it 
38260 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
38270 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67  ..**.** The xPag
38280 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20  ecount() method 
38290 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
382a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
382b0 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73  s currently.** s
382c0 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63  tored in the cac
382d0 68 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61  he supplied as a
382e0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a  n argument..** .
382f0 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20  ** The xFetch() 
38300 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74  method is used t
38310 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61  o fetch a page a
38320 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
38330 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41  ter to it. .** A
38340 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73   'page', in this
38350 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62   context, is a b
38360 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20  uffer of szPage 
38370 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74  bytes aligned at
38380 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f   an.** 8-byte bo
38390 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65  undary. The page
383a0 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69   to be fetched i
383b0 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  s determined by 
383c0 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20  the key. The.** 
383d0 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75  mimimum key valu
383e0 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74  e is 1. After it
383f0 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65   has been retrie
38400 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68  ved using xFetch
38410 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69  , the page .** i
38420 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  s considered to 
38430 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a  be pinned..**.**
38440 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65   If the requeste
38450 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 64  d page is alread
38460 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61  y in the page ca
38470 63 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 6e  che, then a poin
38480 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 61  ter to.** the ca
38490 63 68 65 64 20 62 75 66 66 65 72 20 73 68 6f 75  ched buffer shou
384a0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 77  ld be returned w
384b0 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 73  ith its contents
384c0 20 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 0a   intact. If the.
384d0 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61  ** page is not a
384e0 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 61  lready in the ca
384f0 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 78  che, then the ex
38500 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 72  pected behaviour
38510 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 65   of the.** cache
38520 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62   is determined b
38530 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  y the value of t
38540 68 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 61  he createFlag pa
38550 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a 2a  rameter passed.*
38560 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 63  * to xFetch, acc
38570 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 6f  ording to the fo
38580 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a  llowing table:.*
38590 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
385a0 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 61  er=1 width=85% a
385b0 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20  lign=center>.** 
385c0 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 65    <tr><th>create
385d0 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 64  Flag<th>Expected
385e0 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 20   Behaviour.**   
385f0 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c  <tr><td>0<td>NUL
38600 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  L should be retu
38610 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 63  rned. No new cac
38620 68 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 61  he entry is crea
38630 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74  ted..**   <tr><t
38640 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 65  d>1<td>If create
38650 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 31  Flag is set to 1
38660 2c 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73  , this indicates
38670 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 20   that .**       
38680 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
38690 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e 65  is holding pinne
386a0 64 20 70 61 67 65 73 20 74 68 61 74 20 63 61 6e  d pages that can
386b0 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20   be unpinned.** 
386c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 62                 b
386d0 79 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 20  y writing their 
386e0 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 20  contents to the 
386f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 61  database file (a
38700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
38710 20 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 78     relatively ex
38720 70 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 6f  pensive operatio
38730 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 75  n). In this situ
38740 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ation the.**    
38750 20 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68              cach
38760 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38770 20 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 73   has two choices
38780 3a 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e 20  : it can return 
38790 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  NULL,.**        
387a0 20 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 68          in which
387b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
387c0 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70  l attempt to unp
387d0 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a  in one or more .
387e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  **              
387f0