/ Hex Artifact Content
Login

Artifact 2b7667d7912abe14af4ab84e7c4ed022e734f7ba:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 34 36 20 32 30 30 39 2f 30  n,v 1.446 2009/0
05f0: 34 2f 32 39 20 31 34 3a 33 33 3a 34 34 20 64 72  4/29 14:33:44 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4190: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41a0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
41c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
41d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
41e0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
41f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4200: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4210: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
4220: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4230: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
4240: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
4260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4270: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
4280: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4290: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42a0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
42b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
42c0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
42d0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
42e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
42f0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4300: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
4320: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4330: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
4340: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4350: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4360: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
4370: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4380: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4390: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
43a0: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
43b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
43c0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
43e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
43f0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
4400: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4410: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4420: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4430: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4440: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4450: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4460: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4470: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
4480: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
4490: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
44a0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
44b0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
44c0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
44d0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
44e0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
44f0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4500: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4510: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4520: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4530: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4540: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4550: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4560: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4570: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4580: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
45a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
45b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
45c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
45d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
45e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
45f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4600: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4610: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4620: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4630: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4640: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4650: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4660: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4670: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4680: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4690: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
46a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
46b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
46c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
46d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
46e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
46f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4700: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4710: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4720: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4730: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4740: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4750: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4760: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4770: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4780: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4790: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
47a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
47b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47c0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
47d0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
47e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47f0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4800: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4810: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4820: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4830: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4850: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4860: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4880: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4890: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
48a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48b0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
48c0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
48d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48e0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
48f0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4910: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4920: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4940: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4950: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4970: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4980: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4990: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
49a0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
49b0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
49c0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
49d0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
49e0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
49f0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4a00: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4a10: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4a20: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4a30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4a40: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4a50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4a60: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4a80: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4a90: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4aa0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4ab0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ad0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4ae0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4af0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4b20: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4b30: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4b40: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4b50: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4b60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4b70: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4b80: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4b90: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4ba0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4bb0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4bc0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4bd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4be0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4bf0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4c00: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4c10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4c20: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4c30: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4c40: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4c50: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4c60: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4c70: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4c80: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4c90: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4ca0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4cb0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4cc0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4cd0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4ce0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4cf0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4d00: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4d10: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4d20: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4d30: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4d40: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4d50: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4d60: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4d70: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4d80: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4d90: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4da0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4db0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4dc0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4dd0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4df0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4e00: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4e10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4e20: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4e30: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4e40: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4e50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4e60: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4e70: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4e80: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4e90: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4ea0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4eb0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ec0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
4ed0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
4ee0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
4ef0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
4f00: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
4f10: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
4f20: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
4f30: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
4f40: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
4f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
4f60: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
4f70: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
4f80: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
4f90: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
4fa0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
4fb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
4fd0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
4fe0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
4ff0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5000: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5010: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5020: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5030: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5050: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5060: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
5070: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
5080: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
5090: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
50a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
50b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
50c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
50d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
50f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5100: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5110: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5120: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5130: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5140: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5150: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5160: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
5170: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
5180: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
5190: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
51a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
51b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
51c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
51d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
51e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
51f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5200: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5210: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5220: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5230: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5240: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5250: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5260: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5270: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5280: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5290: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
52a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
52b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
52c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
52d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
52e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
52f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5300: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5310: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5320: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5330: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5340: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5350: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5360: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5370: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5380: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
53a0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
53c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
53e0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
53f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5400: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5410: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5420: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5430: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5440: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5450: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5460: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5470: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5480: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5490: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
54a0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
54b0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
54c0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
54d0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
54e0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
54f0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5500: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5510: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5520: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5530: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5540: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5550: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5560: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5570: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5580: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5590: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
55a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
55b0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
55c0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
55d0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
55e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
55f0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5600: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5610: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5620: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5630: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5640: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5650: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5660: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5670: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5680: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5690: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
56a0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
56b0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
56c0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
56d0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
56e0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
56f0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5700: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5710: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5720: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5730: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5740: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5750: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5760: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5770: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5780: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5790: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
57a0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
57b0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
57c0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
57d0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
57e0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
57f0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5810: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5820: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5830: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5840: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5860: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5870: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5880: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5890: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
58a0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
58b0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
58c0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
58d0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
58e0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
58f0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5900: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5910: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5920: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5930: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5940: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5950: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5960: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5970: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5980: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5990: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
59a0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
59b0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
59c0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
59d0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
59e0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
59f0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5a20: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5a40: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a80: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5aa0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ac0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b00: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b20: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5b40: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5b50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5b60: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5b70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5b80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b90: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5ba0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5bb0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5bc0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5be0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5bf0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5c00: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5c10: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5c20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5c30: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5c40: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5c50: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5c60: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5c70: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5c80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5c90: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5ca0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5cb0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5cc0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5cd0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5ce0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5cf0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5d00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5d10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5d20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5d30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5d40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5d50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5d70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5d80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5d90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5da0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5db0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5dc0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5dd0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5de0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5df0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5e00: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5e10: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5e20: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5e30: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
5e40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5e50: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
5e60: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5e70: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5e80: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5e90: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5ea0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5eb0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ec0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
5ed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
5ef0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5f00: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
5f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
5f20: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
5f30: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
5f40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5f50: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
5f60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
5f70: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
5f80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
5f90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
5fa0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5fb0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
5fc0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
5fd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
5fe0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
5ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6000: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6010: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6020: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6030: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6040: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6050: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6060: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6070: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6080: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6090: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
60a0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
60b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
60d0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
60e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
60f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6100: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6110: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6120: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6130: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6140: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6150: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6160: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6170: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6180: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6190: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
61a0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
61b0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
61c0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
61d0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
61e0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
61f0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6200: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6210: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6220: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6230: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6240: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6250: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6270: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6280: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6290: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
62a0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
62b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
62c0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
62d0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
62e0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
62f0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6300: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6310: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6320: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6330: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6340: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6350: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6360: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6370: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6380: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6390: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
63a0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
63b0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
63c0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
63d0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
63e0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
63f0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6400: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6410: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6420: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6430: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6440: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6450: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6460: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6470: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6480: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
64a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
64b0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
64c0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
64d0: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
64f0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6500: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6510: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6520: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6530: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6540: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6550: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6560: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6570: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6580: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6590: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
65a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
65b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
65c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
65d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
65e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
65f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6600: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6610: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6620: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6630: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6640: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6650: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6660: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6680: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6690: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
66a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
66b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
66c0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
66d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
66e0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
66f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6700: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6710: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6720: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6730: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6740: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6750: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6760: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6770: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6780: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6790: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
67a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
67b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
67c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
67d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
67e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
67f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6800: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6810: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6820: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6830: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6840: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6850: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6860: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6870: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6880: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6890: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
68a0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
68b0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
68c0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
68d0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
68e0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
68f0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6900: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6910: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6920: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6930: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6940: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6950: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6960: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6970: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6980: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6990: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
69a0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
69b0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
69c0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
69d0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
69e0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
69f0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6a00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6a10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6a20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6a30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6a40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6a50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6a60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6a70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6a80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6a90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6aa0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6ab0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6ac0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6ad0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6ae0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6af0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6b00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6b10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6b20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6b30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6b40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6b50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6b60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6b70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6b80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6b90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6ba0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6bb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6bc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6bd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6be0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6bf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6c00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6c10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6c20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6c30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6c40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6c50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6c60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6c70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6c80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6c90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6ca0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6cb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6cc0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6cd0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6ce0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6cf0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6d00: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6d10: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6d20: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6d30: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6d40: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6d50: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6d60: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6d70: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6d80: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6d90: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6da0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6db0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6dc0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6dd0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6de0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6df0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6e00: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6e10: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6e20: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6e30: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6e40: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6e50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6e60: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6e70: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6e80: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6e90: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6ea0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6eb0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ec0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
6ed0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
6ee0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
6ef0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
6f00: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
6f10: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
6f20: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
6f30: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
6f40: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
6f50: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
6f60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
6f70: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
6f80: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
6f90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6fa0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
6fb0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
6fc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6fd0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
6fe0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
6ff0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7000: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7010: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7020: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7040: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7050: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7060: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7070: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7080: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
70a0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
70b0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
70c0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
70d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
70e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
70f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7100: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7110: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7120: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7130: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7150: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7160: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7170: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7180: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7190: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
71a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
71b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
71c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
71d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
71e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
71f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7210: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7220: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7230: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7240: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7250: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7260: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7270: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7280: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7290: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
72a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
72b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
72c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
72d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
72e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
72f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7300: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7310: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7320: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7330: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7340: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7350: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7360: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7370: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7380: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7390: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
73a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
73b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
73c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
73d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
73e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
73f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7400: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7410: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7420: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7430: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7440: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7450: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7460: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7470: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7480: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7490: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
74a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
74b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
74c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
74d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
74e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
74f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7500: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7510: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7520: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7530: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7540: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7550: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7560: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7570: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7580: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7590: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
75a0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
75b0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
75c0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
75d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
75e0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
75f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
7600: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
7610: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7620: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
7630: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
7640: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
7650: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
7660: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
7670: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
7680: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
7690: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
76a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
76b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
76c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
76d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
76e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
76f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
7700: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7710: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
7720: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
7730: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
7740: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
7750: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it in..**.** The
7760: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7770: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7780: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7790: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
77a0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
77b0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
77c0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
77d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
77e0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
77f0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
7800: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
7810: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
7820: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
7830: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
7840: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
7850: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
7860: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
7870: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
7880: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7890: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
78a0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
78b0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
78c0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
78d0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
78e0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
78f0: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7900: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
7910: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
7920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
7930: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
7940: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
7950: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
7960: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
7970: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
7980: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
7990: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
79a0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
79b0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
79c0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
79d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
79e0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
79f0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
7a00: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
7a10: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
7a20: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
7a30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
7a40: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
7a50: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
7a60: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
7a70: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
7a80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
7a90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
7aa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
7ab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
7ac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
7ad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
7ae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7af0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
7b00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
7b10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
7b20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
7b30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
7b40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
7b50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
7b60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
7b70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
7b80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
7b90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
7ba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
7bb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
7bc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
7bd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
7be0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
7bf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
7c00: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
7c10: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7c20: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
7c30: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
7c40: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
7c50: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65  time..**.*/.type
7c60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7c70: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
7c80: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
7c90: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
7ca0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
7cb0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
7cc0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
7cd0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
7ce0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
7cf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
7d00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
7d10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
7d20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
7d30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
7d40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
7d50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
7d60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
7d70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
7d80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
7d90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
7da0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
7db0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
7dc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
7dd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
7de0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
7df0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
7e00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
7e10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
7e20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7e30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
7e40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
7e60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
7e70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
7e80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
7e90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ea0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
7eb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
7ec0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
7ed0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ee0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
7ef0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
7f00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7f10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7f20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7f30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7f40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7f50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
7f60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
7f70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7f80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
7f90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7fb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7fc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7fd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
7fe0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
8000: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
8010: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8020: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8030: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8040: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
8050: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8060: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8070: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8080: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8090: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
80a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
80b0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
80c0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
80d0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
80e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
80f0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
8100: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
8110: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8120: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
8130: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
8140: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
8150: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
8160: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
8170: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
8180: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8190: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
81a0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48  ss VFS method {H
81b0: 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a  11190} <H11140>.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
81d0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
81e0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
81f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
8200: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
8210: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
8220: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
8230: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
8240: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
8250: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
8260: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
8270: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
8280: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
8290: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
82a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
82b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
82c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
82d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
82e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
82f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8300: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
8310: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
8320: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8330: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8340: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8350: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  le..** With SQLI
8360: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
8370: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8380: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
8390: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
83a0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64   readable..*/.#d
83b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83c0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
83d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
83f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8400: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
8410: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    2../*.** CAPI3
8420: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
8430: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
8440: 72 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30  ry {H10130} <S20
8450: 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  000><S30100>.**.
8460: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8470: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8480: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
8490: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
84a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
84b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
84c0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
84d0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
84e0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
84f0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
8500: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
8540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
8550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
8560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
8590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
85a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
85b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
85c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
85d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
85e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
85f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
8600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8610: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
8620: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
8630: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
8640: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
8650: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
8660: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
8670: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
8680: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
8690: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
86a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
86b0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
86c0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
86d0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
86e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
86f0: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
8700: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
8710: 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a  ialize().  Only.
8720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
8730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
8750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
8760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
8770: 65 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  er calls to sqli
8780: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
8790: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
87a0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ps..**.** Among 
87b0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
87c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
87d0: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
87e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
87f0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
8800: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
8810: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
8820: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
8830: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
8840: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8850: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
8860: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
8870: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
8880: 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61   If for some rea
8890: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
88a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
88b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
88c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
88d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
88e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
88f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
8900: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
8910: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
8920: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
8930: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
8940: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
8950: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
8960: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
8970: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
8980: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
8990: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
89a0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
89b0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
89c0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
89d0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
89e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
89f0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
8a00: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
8a10: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
8a20: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
8a30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8a40: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
8a50: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
8a60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
8a70: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
8a80: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8a90: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
8aa0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
8ab0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
8ac0: 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69  ady.  However, i
8ad0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
8ae0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
8af0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
8b00: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
8b10: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
8b20: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
8b30: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
8b40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
8b50: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
8b60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8b70: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
8b80: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8b90: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
8ba0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
8bb0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
8bc0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
8bd0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
8be0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
8bf0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
8c00: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
8c10: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
8c20: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
8c30: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
8c40: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
8c50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
8c60: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
8c70: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
8c80: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
8c90: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
8ca0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
8cb0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
8cc0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
8cd0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
8ce0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
8cf0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
8d00: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
8d10: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
8d20: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
8d30: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
8d40: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
8d50: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
8d60: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
8d70: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
8d80: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
8d90: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
8da0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
8db0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
8dc0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
8dd0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
8de0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
8df0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
8e00: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
8e10: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
8e20: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
8e30: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
8e40: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
8e50: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
8e60: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
8e70: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
8e80: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
8e90: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
8ea0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
8eb0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
8ec0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
8ed0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
8ee0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
8ef0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8f00: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
8f10: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
8f20: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
8f30: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
8f40: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
8f50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8f60: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
8f70: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
8f80: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
8f90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8fa0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
8fb0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
8fc0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
8fd0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
8fe0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8ff0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
9000: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
9010: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
9020: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9030: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
9040: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9050: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
9060: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
9070: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
9080: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
9090: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
90a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78  ompiled for unix
90b0: 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73  , windows, or os
90c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c  /2..** When buil
90d0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
90e0: 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65  forms (using the
90f0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
9100: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
9110: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
9120: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
9130: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
9140: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
9150: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
9160: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9170: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9180: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
9190: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
91a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
91b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
91c0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
91d0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
91e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
91f0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
9200: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
9210: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
9220: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
9230: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9240: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
9250: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
9260: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
9270: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
9280: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9290: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
92a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
92b0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
92c0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31  te Library {H141
92d0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30  00} <S20000><S30
92e0: 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
92f0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
9300: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9310: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
9320: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
9330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
9340: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
9350: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
9360: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
9370: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
9380: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
9390: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
93a0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
93b0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
93c0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
93d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
93e0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
93f0: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
9400: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
9410: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
9420: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
9430: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
9440: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
9450: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9460: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9470: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
9480: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
9490: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
94a0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
94b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
94c0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
94d0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
94e0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
94f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9500: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
9510: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
9520: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
9530: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
9540: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
9550: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
9560: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
9570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
9580: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
9590: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
95a0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74  tdown()]..** Not
95b0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
95c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
95d0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
95e0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
95f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9600: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
9610: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
9620: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
9630: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
9640: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
9650: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9660: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
9670: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
9680: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
9690: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
96a0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
96b0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
96c0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
96d0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
96e0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
96f0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
9700: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
9710: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
9720: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
9730: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
9740: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
9750: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
9760: 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66  *.** When a conf
9770: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
9780: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
9790: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
97a0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
97b0: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
97c0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
97d0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
97e0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
97f0: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
9800: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
9810: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
9820: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  code]..**.** Req
9830: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
9840: 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20  14103] [H14106] 
9850: 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33  [H14120] [H14123
9860: 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31  ] [H14126] [H141
9870: 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31  29] [H14132] [H1
9880: 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38  4135].** [H14138
9890: 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31  ] [H14141] [H141
98a0: 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31  44] [H14147] [H1
98b0: 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b  4150] [H14153] [
98c0: 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d  H14156] [H14159]
98d0: 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31  .** [H14162] [H1
98e0: 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a  4165] [H14168].*
98f0: 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
9900: 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
9910: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
9920: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
9930: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
9940: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9950: 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53  ons  {H14200} <S
9960: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
9970: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
9980: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
9990: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
99a0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
99b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
99c0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
99d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99e0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
99f0: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
9a00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
9a10: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
9a20: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
9a30: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
9a40: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
9a50: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
9a60: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
9a70: 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68  t argument).  Th
9a80: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  e.** sqlite3_db_
9a90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9aa0: 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  ce can only be u
9ab0: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
9ac0: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
9ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ae0: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
9af0: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
9b00: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
9b10: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
9b20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
9b30: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
9b40: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9b50: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
9b60: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
9b70: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
9b80: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
9b90: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
9ba0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
9bb0: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
9bc0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
9bd0: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
9be0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
9bf0: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
9c00: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
9c10: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
9c20: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
9c30: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
9c40: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
9c50: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9c60: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
9c70: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
9c80: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
9c90: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
9ca0: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
9cb0: 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31  .** [H14203] [H1
9cc0: 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b  4206] [H14209] [
9cd0: 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d  H14212] [H14215]
9ce0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
9cf0: 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
9d00: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
9d10: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
9d20: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
9d30: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
9d40: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
9d50: 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31  s {H10155} <S201
9d60: 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  20>.** EXPERIMEN
9d70: 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  TAL.**.** An ins
9d80: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
9d90: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
9da0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
9db0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
9dc0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
9dd0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
9de0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
9df0: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
9e00: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
9e10: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
9e20: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
9e30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e40: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9e50: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
9e60: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
9e70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
9e80: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
9e90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
9ea0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
9eb0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20  IG_MALLOC].  By 
9ec0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
9ed0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
9ee0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
9ef0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
9f00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69  3_config()] duri
9f10: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
9f20: 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  , an.** applicat
9f30: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
9f40: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  an alternative m
9f50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9f60: 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f   subsystem.** fo
9f70: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
9f80: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
9f90: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
9fa0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
9fb0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
9fc0: 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69  s with a built-i
9fd0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
9fe0: 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65  or that is.** pe
9ff0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
a000: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
a010: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
a020: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
a030: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
a040: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
a050: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
a060: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
a070: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
a080: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
a090: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
a0a0: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
a0b0: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
a0c0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
a0d0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
a0e0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
a0f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
a100: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
a110: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
a120: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
a130: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
a140: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
a150: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
a160: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
a170: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
a180: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
a190: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
a1a0: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65  e xMalloc, xFree
a1b0: 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d  , and xRealloc m
a1c0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
a1d0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
a1e0: 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61  loc(), free(), a
a1f0: 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e  nd realloc() fun
a200: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
a210: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
a220: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
a230: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
a240: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a250: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
a260: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
a270: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
a280: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
a290: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
a2a0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
a2b0: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
a2c0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
a2d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
a2e0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
a2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
a300: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
a310: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
a320: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
a330: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
a340: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
a350: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
a360: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
a370: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
a380: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
a390: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
a3a0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
a3b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
a3c0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
a3d0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
a3e0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
a3f0: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
a400: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
a410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
a420: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
a430: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
a440: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
a450: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
a460: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
a470: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
a480: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
a490: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
a4a0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
a4b0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
a4c0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
a4d0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
a4e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
a4f0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
a500: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
a510: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
a520: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
a530: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
a540: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
a550: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
a560: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
a570: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
a580: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a590: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5a0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
a5b0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
a5c0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5d0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
a5e0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
a5f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
a600: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
a610: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
a620: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
a630: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
a640: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
a650: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
a660: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
a670: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
a680: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
a690: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
a6a0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
a6b0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
a6c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
a6d0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
a6e0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
a6f0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
a700: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
a710: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
a720: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
a730: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
a740: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
a750: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
a760: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a770: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
a780: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
a790: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
a7a0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
a7b0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
a7c0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
a7e0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
a7f0: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
a800: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
a810: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
a820: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
a830: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30  s {H10160} <S200
a840: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a850: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
a860: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
a870: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
a880: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
a890: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
a8a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
a8b0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
a8c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
a8d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
a8e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
a8f0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
a900: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
a910: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
a920: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
a930: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
a940: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
a950: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
a960: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
a970: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
a980: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
a990: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
a9a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
a9b0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
a9c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
a9d0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
a9e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a9f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
aa00: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
aa10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
aa20: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
aa30: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
aa40: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
aa50: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
aa60: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
aa70: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
aa80: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
aa90: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
aaa0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
aab0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
aac0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
aad0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
aae0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
aaf0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
ab00: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
ab10: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
ab20: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
ab30: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e  gle thread.</dd>
ab40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ab50: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
ab60: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ab70: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ab80: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ab90: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
aba0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
abb0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
abc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
abd0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
abe0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
abf0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
ac00: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
ac10: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
ac20: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
ac30: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
ac40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
ac50: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ac60: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
ac70: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
ac80: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
ac90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
aca0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
acb0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
acc0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
acd0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
ace0: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
acf0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
ad00: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ad10: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
ad20: 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20  same time.  See 
ad30: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
ad40: 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74  ode].** document
ad50: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
ad60: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
ad70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ad80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ad90: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
ada0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
adb0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
adc0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
add0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ade0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
adf0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ae00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ae10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ae20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ae30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ae40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ae50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ae60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ae70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ae80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ae90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
aea0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
aeb0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
aec0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
aed0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
aee0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
aef0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
af00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
af10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
af20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
af30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
af40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
af50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
af60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
af70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
af80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
af90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
afa0: 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68   time..** See th
afb0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
afc0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
afd0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
afe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
aff0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b000: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
b010: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b020: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b030: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b040: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b050: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b060: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b070: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b080: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b090: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
b0a0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
b0b0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
b0c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b0d0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
b0e0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
b0f0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b100: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b110: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
b120: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
b130: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b140: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
b150: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b160: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
b170: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
b180: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
b190: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
b1a0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
b1b0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
b1c0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
b1d0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b1e0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
b1f0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
b200: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
b210: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
b220: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
b230: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
b240: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
b250: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
b260: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
b270: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
b280: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
b290: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
b2a0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
b2b0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
b2c0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
b2d0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
b2e0: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
b2f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b300: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
b310: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b320: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
b330: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
b340: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
b350: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
b360: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
b370: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
b380: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
b390: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
b3a0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
b3b0: 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65  cs. When disable
b3c0: 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
b3d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
b3e0: 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f  es become .** no
b3f0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
b400: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
b410: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
b420: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
b430: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b440: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
b450: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b460: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
b470: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
b480: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
b490: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a  s()].**   </ul>.
b4a0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
b4b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b4c0: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
b4d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b4e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
b4f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
b500: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
b510: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
b520: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
b530: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
b540: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
b550: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
b560: 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  y, the.** size o
b570: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62  f each scratch b
b580: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
b590: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75  the number of bu
b5a0: 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20  ffers (N).  The 
b5b0: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
b5c0: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
b5d0: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20  e of 16. The sz 
b5e0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b5f0: 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a   be a few bytes.
b600: 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  ** larger than t
b610: 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63  he actual scratc
b620: 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  h space required
b630: 20 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76   due internal ov
b640: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
b650: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
b660: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
b670: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
b680: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
b690: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
b6a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
b6b0: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
b6c0: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
b6d0: 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20  fer at once per 
b6e0: 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20  thread, so.** N 
b6f0: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
b700: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
b710: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b720: 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a  threads.  The sz
b730: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68  .** parameter sh
b740: 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20  ould be 6 times 
b750: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b760: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
b770: 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53   page size..** S
b780: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61  cratch buffers a
b790: 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20  re used as part 
b7a0: 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c  of the btree bal
b7b0: 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  ance operation. 
b7c0: 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65   If.** The btree
b7d0: 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20   balancer needs 
b7e0: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  additional memor
b7f0: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
b800: 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20   provided by.** 
b810: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
b820: 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68  or if no scratch
b830: 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73   buffer space is
b840: 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
b850: 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20   SQLite.** goes 
b860: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
b870: 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20  oc()] to obtain 
b880: 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65  the memory it ne
b890: 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  eds.</dd>.**.** 
b8a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
b8b0: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
b8c0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b8d0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
b8e0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
b8f0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
b900: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
b910: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
b920: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
b930: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
b940: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
b950: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
b960: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
b970: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
b980: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
b990: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
b9a0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
b9b0: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
b9c0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
b9d0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
b9e0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
b9f0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ba00: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ba10: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
ba20: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  he.** memory, th
ba30: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
ba40: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
ba50: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
ba60: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
ba70: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
ba80: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72   must be a power
ba90: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
baa0: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20  512 and 32768.  
bab0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
bac0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
bad0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
bae0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
baf0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
bb00: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
bb10: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
bb20: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
bb30: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bb40: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
bb50: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
bb60: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
bb70: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
bb80: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
bb90: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
bba0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
bbb0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
bbc0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bbd0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
bbe0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
bbf0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
bc00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
bc10: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
bc20: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
bc30: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
bc40: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
bc50: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
bc60: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
bc70: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
bc80: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
bc90: 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a  rmation. </dd>.*
bca0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
bcb0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
bcc0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bcd0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
bce0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
bcf0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
bd00: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
bd10: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
bd20: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
bd30: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
bd40: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
bd50: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
bd60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
bd70: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
bd80: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
bd90: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
bda0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
bdb0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
bdc0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75  e memory, the nu
bdd0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
bde0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
bdf0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
be00: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
be10: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74  n size.  If.** t
be20: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
be30: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
be40: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
be50: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
be60: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
be70: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
be80: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
be90: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
bea0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
beb0: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
bec0: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
bed0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
bee0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
bef0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
bf00: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
bf10: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
bf20: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
bf30: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
bf40: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
bf50: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
bf60: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
bf70: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
bf80: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
bf90: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
bfa0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
bfb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfc0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
bfd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bfe0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
bff0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c000: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c010: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c020: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c030: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c040: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c050: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
c060: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
c070: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
c080: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
c090: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
c0a0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c0b0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
c0c0: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
c0d0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
c0e0: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
c0f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c100: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
c110: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c120: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c130: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c140: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c150: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c160: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c170: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
c180: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
c190: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
c1a0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
c1b0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c1c0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c1d0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
c1e0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
c1f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
c200: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
c210: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
c220: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
c230: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
c240: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
c250: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
c260: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
c270: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
c280: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
c290: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c2a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c2b0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c2c0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DE</dt>.** <dd>T
c2d0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c2e0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
c2f0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
c300: 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
c310: 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f  ory allcation lo
c320: 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61  okaside optimiza
c330: 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74  tion.  The first
c340: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
c350: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
c360: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
c370: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
c380: 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
c390: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
c3a0: 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
c3b0: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
c3c0: 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
c3d0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c3e0: 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a  FIG_PCACHE</dt>.
c3f0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c400: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c410: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c420: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c430: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
c440: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
c450: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
c460: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
c470: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
c480: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
c490: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
c4a0: 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d  ation.  SQLite m
c4b0: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
c4c0: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
c4d0: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
c4e0: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
c4f0: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
c500: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c510: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
c520: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
c530: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c540: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c550: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c560: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
c570: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
c580: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
c590: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
c5a0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
c5b0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
c5c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
c5d0: 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  that object.</dd
c5e0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c610: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
c620: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c630: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
c640: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
c650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c660: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
c670: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
c680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c690: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
c6a0: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
c6b0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c6c0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
c6d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c6e0: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
c6f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c700: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
c720: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
c730: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
c740: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
c750: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c760: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
c770: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
c780: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
c790: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c7a0: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
c7b0: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
c7c0: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
c7d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c7e0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c7f0: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
c800: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
c810: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c820: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
c830: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c840: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c850: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c860: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
c870: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
c880: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c890: 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
c8a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
c8b0: 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
c8c0: 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
c8d0: 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
c8e0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c8f0: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
c900: 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
c910: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
c920: 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
c930: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
c940: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c960: 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
c970: 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
c980: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
c990: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
c9a0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
c9b0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
c9c0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
c9d0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
c9e0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
c9f0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
ca00: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ca10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ca20: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ca30: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
ca40: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ca50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
ca60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ca70: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
ca80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca90: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
caa0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
cab0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
cac0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
cad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cae0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
caf0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
cb00: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
cb10: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
cb20: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
cb30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cb40: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
cb50: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
cb60: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
cb70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cb80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
cb90: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
cba0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
cbb0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
cbc0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
cbd0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
cbe0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
cbf0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
cc00: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
cc10: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
cc20: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
cc30: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
cc40: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
cc50: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
cc60: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
cc70: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
cc80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
cc90: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
cca0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
ccb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
ccc0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
ccd0: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
cce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
ccf0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cd00: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
cd10: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
cd20: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
cd30: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
cd40: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
cd50: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
cd60: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
cd70: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
cd80: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
cd90: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
cda0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
cdb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cdc0: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
cdd0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
cde0: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
cdf0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
ce00: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
ce10: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
ce20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ce30: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
ce40: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
ce50: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ce60: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
ce70: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
ce80: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
ce90: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
cea0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
ceb0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
cec0: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
cee0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
cef0: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
cf00: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
cf10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
cf20: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
cf30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
cf40: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
cf50: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
cf60: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
cf70: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
cf80: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
cf90: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
cfa0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
cfb0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
cfc0: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
cfd0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
cfe0: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
cff0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d000: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
d010: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
d020: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
d030: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
d040: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d  nts:.** [H12201]
d050: 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74   [H12202].*/.int
d060: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
d070: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
d080: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
d090: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
d0a0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
d0b0: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
d0c0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
d0d0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
d0e0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
d0f0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
d100: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
d110: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
d120: 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
d130: 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20  id"]. The rowid 
d140: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
d150: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
d160: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
d170: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
d180: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
d190: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
d1a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
d1b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
d1c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
d1d0: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68  olumns. If.** th
d1e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
d1f0: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
d200: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
d210: 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
d220: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
d230: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
d240: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
d250: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d260: 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
d270: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
d280: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
d290: 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
d2a0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
d2b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
d2c0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
d2d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d2e0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
d2f0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
d300: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
d310: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
d320: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d330: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
d340: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
d350: 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
d360: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
d370: 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
d380: 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
d390: 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
d3a0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
d3b0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
d3c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
d3d0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
d3e0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
d3f0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
d400: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d410: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
d420: 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
d430: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
d440: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
d450: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
d460: 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54  **.** An [INSERT
d470: 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
d480: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
d490: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
d4a0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
d4b0: 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
d4c0: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
d4d0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d4e0: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
d4f0: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
d500: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
d510: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
d520: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
d530: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
d540: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
d550: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
d560: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
d570: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
d580: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
d590: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
d5a0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
d5b0: 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
d5c0: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
d5d0: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
d5e0: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
d5f0: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
d600: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
d610: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
d620: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
d630: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
d640: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
d650: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
d660: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
d670: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
d680: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
d690: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
d6a0: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
d6b0: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
d6c0: 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
d6d0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
d6e0: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
d6f0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
d700: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
d710: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
d720: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
d730: 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32   [H12221] [H1222
d740: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
d750: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
d760: 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
d770: 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
d780: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
d790: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
d7a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
d7b0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d7c0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
d7d0: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
d7e0: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
d7f0: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
d800: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
d810: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
d820: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
d830: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
d840: 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
d850: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
d860: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
d870: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
d880: 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
d890: 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
d8a0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
d8b0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
d8c0: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
d8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d8e0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
d8f0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
d900: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
d910: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
d920: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
d930: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
d940: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
d950: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
d960: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
d970: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
d980: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
d990: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
d9a0: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
d9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d9c0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
d9d0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
d9e0: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
d9f0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
da00: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
da10: 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
da20: 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
da30: 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
da40: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
da50: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
da60: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
da70: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
da80: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
da90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
daa0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
dab0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
dac0: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
dad0: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
dae0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
daf0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
db00: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67  ers..**.** Chang
db10: 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
db20: 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
db30: 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
db40: 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
db50: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
db60: 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
db70: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
db80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ted..**.** A "ro
db90: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
dba0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
dbb0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
dbc0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
dbd0: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
dbe0: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
dbf0: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
dc00: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
dc10: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
dc20: 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
dc30: 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
dc40: 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
dc50: 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
dc60: 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
dc70: 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
dc80: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
dc90: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
dca0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
dcb0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
dcc0: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
dcd0: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
dce0: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
dcf0: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
dd00: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
dd10: 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
dd20: 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
dd30: 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
dd40: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
dd50: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
dd60: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
dd70: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
dd80: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
dd90: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
dda0: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
ddb0: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
ddc0: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
ddd0: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
dde0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
ddf0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
de00: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
de10: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
de20: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
de30: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
de40: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
de50: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
de60: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
de70: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
de80: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
de90: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
dea0: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
deb0: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
dec0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
ded0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
dee0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
def0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
df00: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
df10: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
df20: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
df30: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
df40: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
df50: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
df60: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
df70: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
df80: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
df90: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
dfa0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
dfb0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
dfc0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
dfd0: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
dfe0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
dff0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
e000: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
e010: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
e020: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
e030: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
e040: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
e050: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
e060: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
e070: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
e080: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
e090: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
e0a0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
e0b0: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
e0c0: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
e0d0: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
e0e0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
e0f0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
e100: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
e110: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
e120: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
e130: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
e140: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
e150: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
e160: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
e170: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
e180: 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68 65  nterface and the
e190: 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
e1a0: 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a  es pragma]..**.*
e1b0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
e1c0: 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32  ** [H12241] [H12
e1d0: 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  243].**.** If a 
e1e0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
e1f0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
e200: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
e210: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
e220: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
e230: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
e240: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
e250: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
e260: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
e270: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
e280: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
e290: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
e2a0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
e2b0: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
e2c0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
e2d0: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
e2e0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
e2f0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e300: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e310: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
e320: 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
e330: 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
e340: 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
e350: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
e360: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e370: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
e380: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69  ..** The count i
e390: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
e3a0: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 0a 2a 2a  ges from all .**
e3b0: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
e3c0: 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
e3d0: 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a  exts.  However,.
e3e0: 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
e3f0: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
e400: 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
e410: 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
e420: 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
e430: 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
e440: 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
e450: 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
e460: 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
e470: 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
e480: 65 73 20 6e 6f 74 20 72 6f 77 73 20 6f 66 20 76  es not rows of v
e490: 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
e4a0: 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
e4b0: 69 67 67 65 72 5d 2c 20 74 68 6f 75 67 68 20 69  igger], though i
e4c0: 66 0a 2a 2a 20 74 68 65 20 49 4e 53 54 45 41 44  f.** the INSTEAD
e4d0: 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
e4e0: 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
e4f0: 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
e500: 67 65 73 20 61 72 65 0a 2a 2a 20 63 6f 75 6e 74  ges are.** count
e510: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ed..** The chang
e520: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
e530: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
e540: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
e550: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
e560: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
e570: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
e580: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
e590: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
e5a0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
e5b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
e5c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
e5d0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
e5e0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
e5f0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
e600: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
e610: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
e620: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
e630: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
e640: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e650: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e660: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e670: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e680: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e690: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e6a0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
e6b0: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
e6c0: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
e6d0: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e6e0: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
e6f0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
e700: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e710: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
e720: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
e730: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
e740: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
e750: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
e760: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e770: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
e780: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
e790: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
e7a0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
e7b0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
e7c0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
e7d0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
e7e0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
e7f0: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
e800: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
e810: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
e820: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
e830: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
e840: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
e850: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
e860: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
e870: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
e880: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
e890: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
e8a0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
e8b0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
e8c0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
e8d0: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
e8e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
e8f0: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
e900: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
e910: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
e920: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
e930: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e940: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
e950: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
e960: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
e970: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
e980: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
e990: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
e9a0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
e9b0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
e9c0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
e9d0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
e9e0: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
e9f0: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ea00: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
ea10: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ea20: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
ea30: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ea40: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
ea50: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ea60: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ea70: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ea80: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ea90: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
eaa0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
eab0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
eac0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ead0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
eae0: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
eaf0: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
eb00: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
eb10: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
eb20: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
eb30: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
eb40: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ally..**.** The 
eb50: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
eb60: 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
eb70: 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
eb80: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
eb90: 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
eba0: 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
ebb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
ebc0: 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e  complete.  Any n
ebd0: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
ebe0: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ebf0: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
ec00: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ec10: 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
ec20: 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
ec30: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
ec40: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
ec50: 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
ec60: 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
ec70: 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
ec80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
ec90: 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
eca0: 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65  .  New SQL state
ecb0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
ecc0: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
ecd0: 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
ece0: 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
ecf0: 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
ed00: 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
ed10: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
ed20: 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61  rrupt()..** A ca
ed30: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ed40: 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
ed50: 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
ed60: 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
ed70: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
ed80: 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
ed90: 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
eda0: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
edb0: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
edc0: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
edd0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ede0: 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
edf0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
ee00: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31  ents:.** [H12271
ee10: 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a  ] [H12272].**.**
ee20: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
ee30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
ee40: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
ee50: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
ee60: 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
ee70: 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
ee80: 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
ee90: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
eea0: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
eeb0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
eec0: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
eed0: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
eee0: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
eef0: 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30   {H10510} <S7020
ef00: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
ef10: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
ef20: 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
ef30: 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
ef40: 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
ef50: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
ef60: 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
ef70: 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
ef80: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
ef90: 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
efa0: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
efb0: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
efc0: 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
efd0: 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
efe0: 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
eff0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
f000: 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
f010: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
f020: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
f030: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
f040: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
f050: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
f060: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
f070: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
f080: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
f090: 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
f0a0: 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
f0b0: 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
f0c0: 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
f0d0: 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
f0e0: 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
f0f0: 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
f100: 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
f110: 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
f120: 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
f130: 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
f140: 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
f150: 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
f160: 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
f170: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
f180: 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
f190: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
f1a0: 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
f1b0: 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70  inator.  Whitesp
f1c0: 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
f1d0: 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
f1e0: 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
f1f0: 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
f200: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f210: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
f220: 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
f230: 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
f240: 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
f250: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
f260: 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
f270: 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
f280: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f290: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
f2a0: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
f2b0: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
f2c0: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
f2d0: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
f2e0: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
f2f0: 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
f300: 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
f310: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
f320: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f330: 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
f340: 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
f350: 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
f360: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f370: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f380: 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
f390: 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
f3a0: 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
f3b0: 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
f3c0: 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
f3d0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
f3e0: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
f3f0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
f400: 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
f410: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
f420: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
f430: 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
f440: 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  mplete..**.** Re
f450: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
f460: 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a  511] [H10512].**
f470: 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
f480: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
f490: 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
f4a0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
f4b0: 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
f4c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
f4d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
f4e0: 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
f4f0: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
f500: 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
f510: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
f520: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
f530: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
f540: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
f550: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
f560: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
f570: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
f580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f590: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
f5a0: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
f5b0: 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
f5c0: 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
f5d0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
f5e0: 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
f5f0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
f600: 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
f610: 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
f620: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
f630: 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
f640: 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
f650: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
f660: 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
f670: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
f680: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
f690: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
f6a0: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
f6b0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
f6c0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
f6d0: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
f6e0: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
f6f0: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
f700: 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
f710: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
f720: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
f730: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
f740: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
f750: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
f760: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
f770: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
f780: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
f790: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
f7a0: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
f7b0: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
f7c0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
f7d0: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
f7e0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
f7f0: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
f800: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
f810: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
f820: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
f830: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
f840: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
f850: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
f860: 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
f870: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
f880: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
f890: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
f8a0: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
f8b0: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
f8c0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
f8d0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
f8e0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
f8f0: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
f900: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
f910: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
f920: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
f930: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
f940: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
f950: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
f960: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
f970: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
f980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
f990: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
f9a0: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
f9b0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
f9c0: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
f9d0: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
f9e0: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
f9f0: 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
fa00: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
fa10: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
fa20: 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
fa30: 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
fa40: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
fa50: 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
fa60: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
fa70: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
fa80: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
fa90: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
faa0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fab0: 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
fac0: 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
fad0: 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
fae0: 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
faf0: 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
fb00: 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
fb10: 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
fb20: 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
fb30: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
fb40: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
fb50: 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
fb60: 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
fb70: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
fb80: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
fb90: 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
fba0: 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
fbb0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
fbc0: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
fbd0: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
fbe0: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
fbf0: 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
fc00: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
fc10: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
fc20: 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
fc30: 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
fc40: 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
fc50: 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
fc60: 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
fc70: 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
fc80: 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
fc90: 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
fca0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
fcb0: 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
fcc0: 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
fcd0: 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
fce0: 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
fcf0: 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
fd00: 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
fd10: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
fd20: 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
fd30: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
fd40: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
fd50: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
fd60: 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
fd70: 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
fd80: 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
fd90: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
fda0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
fdb0: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
fdc0: 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
fdd0: 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
fde0: 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
fdf0: 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
fe00: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
fe10: 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
fe20: 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
fe30: 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
fe40: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
fe50: 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
fe60: 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
fe70: 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
fe80: 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
fe90: 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
fea0: 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
feb0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
fec0: 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
fed0: 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
fee0: 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
fef0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
ff00: 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
ff10: 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
ff20: 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
ff30: 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
ff40: 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
ff50: 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
ff60: 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
ff70: 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
ff80: 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
ff90: 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
ffa0: 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
ffb0: 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
ffc0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
ffd0: 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
ffe0: 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
fff0: 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
10000 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
10010 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
10020 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
10030 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
10040 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
10050 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
10060 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
10070 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
10080 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
10090 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
100a0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
100b0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
100c0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
100d0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
100e0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
100f0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
10100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10110 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
10120 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
10130 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
10140 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
10150 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
10160 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
10170 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10180 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
10190 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
101a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
101b0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
101c0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
101d0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
101e0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
101f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
10200 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
10210 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
10220 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
10230 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
10240 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
10250 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
10260 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
10270 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32  ** [H12311] [H12
10280 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48  312] [H12314] [H
10290 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a  12316] [H12318].
102a0 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  **.** A busy han
102b0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
102c0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
102d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
102e0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
102f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
10300 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
10310 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
10320 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10330 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
10340 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
10350 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
10360 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
10370 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33  sy Timeout {H123
10380 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  40} <S40410>.**.
10390 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
103a0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
103b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
103c0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
103d0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
103e0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
103f0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
10400 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
10410 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
10420 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
10430 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
10440 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
10450 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
10460 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
10470 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
10480 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  H12343} After "m
10490 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
104a0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
104b0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
104c0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
104d0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
104e0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
104f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10500 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10510 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
10520 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
10530 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
10540 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
10550 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
10560 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
10570 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
10580 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
10590 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
105a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
105b0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
105c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
105d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
105e0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
105f0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
10600 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
10610 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
10620 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10630 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
10640 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
10650 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
10660 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
10670 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
10680 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10690 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b  s:.** [H12341] [
106a0 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d  H12343] [H12344]
106b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
106c0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
106d0 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
106e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106f0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
10700 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
10710 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37  g Queries {H1237
10720 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
10730 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
10740 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
10750 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
10760 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
10770 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
10780 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10790 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
107a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
107b0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
107c0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
107d0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
107e0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
107f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
10800 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
10810 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
10820 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
10830 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
10840 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
10850 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
10860 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
10870 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
10880 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
10890 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
108a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
108b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
108c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
108d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
108e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
108f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
10900 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
10910 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
10920 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
10930 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
10940 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
10950 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
10960 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
10970 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
10980 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
10990 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
109a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
109b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
109c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
109d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
109e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
109f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
10a00 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
10a10 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
10a20 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
10a30 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
10a40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
10a50 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
10a60 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
10a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
10a80 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
10a90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
10aa0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
10ab0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
10ac0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
10ad0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
10ae0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
10af0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
10b00 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
10b10 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
10b20 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
10b30 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
10b40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
10b50 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
10b60 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
10b70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
10b80 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
10b90 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
10ba0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
10bb0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
10bc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
10bd0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
10be0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
10bf0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
10c00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
10c10 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
10c20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
10c30 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
10c40 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
10c50 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 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 72 65 20  te>.**.** There 
10c80 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
10c90 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
10ca0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
10cb0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
10cc0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
10cd0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
10ce0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10cf0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
10d00 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
10d10 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
10d20 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
10d30 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
10d40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
10d50 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
10d60 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
10d70 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
10d80 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
10d90 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
10da0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10db0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
10dc0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
10dd0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
10de0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10df0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
10e00 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
10e10 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
10e20 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
10e30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
10e40 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
10e50 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
10e60 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
10e70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
10e80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
10e90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
10ea0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
10eb0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
10ec0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
10ed0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
10ee0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
10ef0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
10f00 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
10f10 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
10f20 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
10f30 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
10f40 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
10f50 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
10f60 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
10f70 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
10f80 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
10f90 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
10fa0 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
10fb0 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
10fc0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
10fd0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10fe0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
10ff0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
11000 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
11010 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
11020 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
11030 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
11040 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11050 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
11060 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
11070 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
11080 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
11090 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
110a0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
110b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
110c0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
110d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
110e0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
110f0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
11100 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
11110 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
11120 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
11130 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
11140 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
11150 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
11160 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
11170 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
11180 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11190 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
111a0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
111b0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
111c0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
111d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
111e0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
111f0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
11200 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
11210 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
11220 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
11230 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
11240 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
11250 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
11260 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
11270 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
11280 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
11290 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
112a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
112b0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
112c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
112d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
112e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33  ements:.** [H123
112f0 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31  71] [H12373] [H1
11300 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b  2374] [H12376] [
11310 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d  H12379] [H12382]
11320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11330 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
11340 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
11350 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
11360 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
11370 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
11380 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
11390 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
113a0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
113b0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
113c0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
113d0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
113e0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
113f0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
11400 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11410 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
11420 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
11430 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
11440 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
11450 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
11460 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
11470 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
11480 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
11490 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
114a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
114b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
114c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
114d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
114e0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
114f0 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
11500 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
11510 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
11520 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
11530 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
11540 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
11550 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
11560 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
11570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
11580 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
11590 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
115a0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
115b0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
115c0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
115d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
115e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
115f0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
11600 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
11610 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
11620 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
11630 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
11640 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75  ee()].  Both rou
11650 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
11660 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
11670 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
11680 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
11690 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
116a0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
116b0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
116c0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
116d0 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
116e0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
116f0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
11700 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
11710 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
11720 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
11730 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
11740 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
11750 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
11760 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
11770 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
11780 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
11790 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
117a0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
117b0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
117c0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
117d0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
117e0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
117f0 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
11800 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
11810 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
11820 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
11830 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
11840 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
11850 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
11860 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
11870 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
11880 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
11890 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
118a0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
118b0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
118c0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
118d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
118e0 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
118f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
11900 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
11910 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
11920 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
11930 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
11940 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
11950 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
11960 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
11970 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
11980 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
11990 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
119a0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
119b0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
119c0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
119d0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
119e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
119f0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
11a00 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
11a10 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
11a20 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
11a30 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
11a40 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
11a50 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
11a60 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
11a70 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
11a80 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
11a90 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
11aa0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
11ab0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
11ac0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
11ad0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
11ae0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
11af0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
11b00 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
11b10 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
11b20 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
11b30 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
11b40 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
11b50 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
11b60 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
11b70 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
11b80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
11b90 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
11ba0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
11bb0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
11bc0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
11bd0 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
11be0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
11bf0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
11c00 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
11c10 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
11c20 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
11c30 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
11c40 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
11c50 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
11c60 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
11c70 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
11c80 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
11c90 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
11ca0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
11cb0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
11cc0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
11cd0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
11ce0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
11cf0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
11d00 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
11d10 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
11d20 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
11d30 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
11d40 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
11d50 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
11d60 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
11d70 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
11d80 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
11d90 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
11da0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11db0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
11dc0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
11dd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
11de0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
11df0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
11e00 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
11e10 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
11e20 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
11e30 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
11e40 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
11e50 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
11e60 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
11e70 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
11e80 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
11e90 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11ea0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
11eb0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
11ec0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
11ed0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
11ee0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
11ef0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
11f00 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
11f10 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
11f20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
11f30 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
11f40 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
11f50 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
11f60 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
11f70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
11f80 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
11f90 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
11fa0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
11fb0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
11fc0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
11fd0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
11fe0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
11ff0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
12000 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
12010 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
12020 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
12030 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
12040 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12050 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
12060 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
12070 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
12080 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
12090 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
120a0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
120b0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
120c0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
120d0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
120e0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51  al..**.** The %Q
120f0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
12100 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
12110 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
12120 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
12130 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
12140 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
12150 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
12160 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
12170 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
12180 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
12190 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
121a0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
121b0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
121c0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
121d0 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
121e0 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
121f0 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  n.  So, for exam
12200 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
12210 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
12220 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12230 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
12240 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
12250 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
12260 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
12270 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
12280 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12290 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
122a0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
122b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
122c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
122d0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
122e0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
122f0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
12300 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
12310 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
12320 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
12330 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
12340 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
12350 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
12360 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
12370 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
12380 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
12390 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
123a0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
123b0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
123c0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
123d0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
123e0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
123f0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
12400 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
12410 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
12420 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b  s:.** [H17403] [
12430 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d  H17406] [H17407]
12440 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
12450 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
12460 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
12470 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
12480 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
12490 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
124a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
124b0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
124c0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
124d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
124e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
124f0 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33   Subsystem {H173
12500 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  00} <S20000>.**.
12510 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
12520 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
12530 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
12540 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
12550 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
12560 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12570 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
12580 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
12590 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
125a0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
125b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
125c0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
125d0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
125e0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
125f0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
12600 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
12610 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
12620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12630 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
12640 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
12650 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
12660 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
12670 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
12680 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
12690 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
126a0 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  er..** If sqlite
126b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
126c0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
126d0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
126e0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
126f0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
12700 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72  ter.  If the par
12710 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
12720 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
12730 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
12740 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
12750 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
12760 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
12770 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ter..**.** Calli
12780 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
12790 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
127a0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
127b0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
127c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
127d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
127e0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
127f0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
12800 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
12810 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  sed.  The sqlite
12820 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
12830 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
12840 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
12850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
12860 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
12870 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
12880 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
12890 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
128a0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
128b0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
128c0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
128d0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
128e0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
128f0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
12900 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
12910 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
12920 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
12930 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
12940 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
12950 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
12960 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
12970 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
12980 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
12990 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
129a0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
129b0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
129c0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
129d0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
129e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
129f0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
12a00 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
12a10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
12a20 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
12a30 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
12a40 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
12a50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12a60 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
12a70 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
12a80 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
12a90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
12aa0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
12ab0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
12ac0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
12ad0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
12ae0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
12af0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
12b00 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
12b10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
12b20 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
12b30 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
12b40 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
12b50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
12b60 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
12b70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12b80 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
12b90 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
12ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12bb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
12bc0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
12bd0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
12be0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
12bf0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
12c00 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
12c10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
12c20 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
12c30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12c40 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
12c50 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
12c60 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
12c70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
12c80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
12c90 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
12ca0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
12cb0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
12cc0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
12cd0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
12ce0 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
12cf0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
12d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
12d10 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
12d20 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
12d30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
12d40 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
12d50 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
12d60 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
12d70 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
12d80 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
12d90 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
12da0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
12db0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
12dc0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
12dd0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
12de0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
12df0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
12e00 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
12e10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
12e20 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
12e30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
12e40 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
12e50 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
12e60 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
12e70 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
12e80 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
12e90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
12ea0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12eb0 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
12ec0 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
12ed0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
12ee0 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
12ef0 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
12f00 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48  C library..** {H
12f10 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
12f20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
12f30 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
12f40 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
12f50 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
12f60 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
12f70 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
12f80 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
12f90 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
12fa0 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
12fb0 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
12fc0 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
12fd0 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
12fe0 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
12ff0 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
13000 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
13010 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13020 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
13030 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
13040 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
13050 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
13060 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13070 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
13080 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13090 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
130a0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
130b0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
130c0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
130d0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
130e0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
130f0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
13100 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13110 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
13120 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
13130 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
13140 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
13150 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
13160 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
13170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
13180 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
13190 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
131a0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
131b0 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
131c0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
131d0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
131e0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
131f0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
13200 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
13210 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
13220 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
13230 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
13240 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
13250 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
13260 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
13270 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
13280 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
13290 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
132a0 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
132b0 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
132c0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
132d0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
132e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
132f0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
13300 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
13310 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
13320 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33  * [H17303] [H173
13330 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31  04] [H17305] [H1
13340 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b  7306] [H17310] [
13350 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d  H17312] [H17315]
13360 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31   [H17318].** [H1
13370 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b  7321] [H17322] [
13380 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68  H17323].**.** Th
13390 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
133a0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
133b0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
133c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
133d0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
133e0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
133f0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
13400 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
13410 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13420 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13430 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
13440 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
13450 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
13460 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
13470 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13480 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
13490 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
134a0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
134b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
134c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
134d0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
134e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
134f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
13500 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
13510 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
13520 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
13530 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
13540 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
13550 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
13560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13570 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13580 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
13590 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
135a0 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
135b0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
135c0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
135d0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
135e0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
135f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
13600 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
13610 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
13620 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
13630 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
13640 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
13650 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
13660 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
13670 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  m..**.** Require
13680 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37  ments:.** [H1737
13690 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37  1] [H17373] [H17
136a0 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f  374] [H17375].*/
136b0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
136c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
136d0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
136e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
136f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
13700 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
13710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13720 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
13730 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
13740 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30   {H17390} <S2000
13750 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
13760 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
13770 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
13780 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
13790 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
137a0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
137b0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
137c0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
137d0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
137e0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
137f0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
13800 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
13810 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
13820 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
13830 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
13840 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
13850 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
13860 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
13870 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
13880 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
13890 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
138a0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
138b0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
138c0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
138d0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
138e0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
138f0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
13900 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
13910 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
13920 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
13930 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
13940 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
13950 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
13960 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
13970 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
13980 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
13990 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
139a0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
139b0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
139c0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
139d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
139e0 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
139f0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
13a00 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
13a10 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
13a20 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
13a30 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
13a40 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
13a50 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
13a60 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
13a70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13a80 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32  ents:.** [H17392
13a90 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ].*/.void sqlite
13aa0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
13ab0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
13ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13ad0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
13ae0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
13af0 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
13b00 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
13b10 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
13b20 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
13b30 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
13b40 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
13b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13b60 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
13b70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13b80 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
13b90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13ba0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
13bb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
13bc0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
13bd0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
13be0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
13bf0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
13c00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
13c10 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
13c20 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
13c30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
13c40 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
13c50 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
13c60 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
13c70 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
13c80 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
13c90 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
13ca0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
13cb0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
13cc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13cd0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
13ce0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
13cf0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
13d00 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
13d10 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
13d20 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
13d30 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
13d40 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
13d50 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
13d60 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
13d70 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
13d80 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
13d90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
13da0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
13db0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
13dc0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
13dd0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
13de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
13df0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
13e00 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
13e10 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
13e20 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
13e30 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
13e40 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
13e50 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
13e60 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
13e70 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
13e80 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
13e90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
13ea0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
13eb0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
13ec0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
13ed0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
13ee0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
13ef0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
13f00 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
13f10 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
13f20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
13f30 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
13f40 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
13f50 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
13f60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
13f70 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
13f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
13f90 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
13fa0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
13fb0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
13fc0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
13fd0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
13fe0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
13ff0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
14000 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49  ss is denied.  I
14010 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
14020 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
14030 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
14040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
14050 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
14060 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
14070 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14080 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
14090 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
140a0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
140b0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
140c0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
140d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
140e0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
140f0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
14100 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
14110 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
14120 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
14130 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
14140 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
14150 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
14160 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
14170 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
14180 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   table..**.** Th
14190 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
141a0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
141b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
141c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
141d0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
141e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
141f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
14200 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20   interface. The 
14210 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14220 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
14230 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
14240 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
14250 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
14260 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
14270 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
14280 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
14290 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72  orized. The thir
142a0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
142b0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
142c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
142d0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
142e0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
142f0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
14300 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
14310 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
14320 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
14330 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
14340 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
14350 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14360 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
14370 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
14380 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
14390 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
143a0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
143b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
143c0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
143d0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
143e0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
143f0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
14400 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
14410 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
14420 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
14430 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
14440 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
14450 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
14460 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
14470 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
14480 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
14490 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
144a0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
144b0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
144c0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
144d0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
144e0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
144f0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
14500 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
14510 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
14520 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
14530 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
14540 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
14550 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
14560 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
14570 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
14580 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
14590 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
145a0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
145b0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
145c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
145d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
145e0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
145f0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
14600 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
14610 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
14620 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
14630 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
14640 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
14650 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
14660 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
14670 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
14680 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
14690 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
146a0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
146b0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
146c0 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
146d0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
146e0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
146f0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
14700 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
14710 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
14720 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
14730 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
14740 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
14750 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
14760 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
14770 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
14780 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
14790 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
147a0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
147b0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
147c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
147d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
147e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
147f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
14800 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
14810 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
14820 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
14830 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
14840 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
14850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14860 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
14870 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
14880 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
14890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
148a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
148b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
148c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
148d0 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
148e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
148f0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
14900 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
14910 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
14920 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
14930 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  eprepared during
14940 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14950 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
14960 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
14970 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
14980 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
14990 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
149a0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
149b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
149c0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
149d0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
149e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
149f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
14a00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14a10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
14a20 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
14a30 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
14a40 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
14a50 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
14a60 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
14a70 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
14a80 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
14a90 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
14aa0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
14ab0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
14ac0 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48  501] [H12502] [H
14ad0 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20  12503] [H12504] 
14ae0 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36  [H12505] [H12506
14af0 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35  ] [H12507] [H125
14b00 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20  10].** [H12511] 
14b10 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30  [H12512] [H12520
14b20 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35  ] [H12521] [H125
14b30 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  22].*/.int sqlit
14b40 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
14b50 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
14b60 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
14b70 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14b80 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
14b90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
14ba0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
14bb0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
14bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14bd0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
14be0 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d  n Codes {H12590}
14bf0 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
14c00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
14c10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
14c20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
14c30 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
14c40 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
14c50 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
14c60 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
14c70 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
14c80 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
14c90 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
14ca0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
14cb0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
14cc0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
14cd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
14ce0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
14cf0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
14d00 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
14d10 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
14d20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14d30 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
14d40 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
14d50 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
14d60 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
14d70 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
14d80 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
14d90 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
14da0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
14db0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
14dc0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
14dd0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
14de0 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35  s {H12550} <H125
14df0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
14e00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
14e10 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
14e20 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
14e30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
14e40 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
14e50 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
14e60 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
14e70 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
14e80 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
14e90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14ea0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
14eb0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
14ec0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
14ed0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
14ee0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
14ef0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
14f00 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
14f10 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
14f20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14f30 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
14f40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
14f50 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
14f60 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
14f70 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
14f80 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
14f90 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
14fa0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
14fb0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
14fc0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
14fd0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
14fe0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
14ff0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
15000 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
15010 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
15020 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
15030 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
15040 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
15050 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
15060 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15070 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
15080 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
15090 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
150a0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
150b0 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
150c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
150d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
150e0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
150f0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
15100 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
15110 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
15120 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
15130 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
15140 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
15150 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
15160 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
15170 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
15180 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52  QL code..**.** R
15190 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
151a0 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32  [H12551] [H12552
151b0 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35  ] [H12553] [H125
151c0 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  54].*/./********
151d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
151e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
151f0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
15200 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
15210 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
15220 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
15230 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
15240 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
15250 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
15260 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15270 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
15280 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
15290 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
152a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
152b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
152c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
152d0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
152e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
152f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15310 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
15320 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
15330 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15340 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15360 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
15370 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
15380 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
15390 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
153a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
153b0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
153c0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
153d0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
153e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
153f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15400 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
15410 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
15420 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15430 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15450 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
15460 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
15470 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
15480 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
154a0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
154b0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
154c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
154d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
154e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
154f0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
15500 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
15510 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
15520 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15530 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
15540 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
15550 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
15560 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15570 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15580 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15590 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
155a0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
155b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
155c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
155d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
155e0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
155f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15600 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15610 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15620 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15630 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
15640 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
15650 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
15660 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15670 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15680 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
15690 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
156a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
156b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
156c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
156d0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
156e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
156f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15700 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15710 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
15720 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
15730 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15740 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15750 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15760 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
15770 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
15780 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15790 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
157a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
157b0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
157c0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
157d0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
157e0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
157f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15800 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
15810 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
15820 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
15830 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
15840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15850 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
15860 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
15870 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
15880 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
158a0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
158b0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
158c0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
158d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
158e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
158f0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
15900 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
15910 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
15920 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
15930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
15940 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
15950 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
15960 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
15970 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
15990 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
159a0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
159b0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
159c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
159d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
159e0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
159f0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
15a00 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
15a10 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15a20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
15a30 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
15a40 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
15a50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15a60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15a70 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
15a80 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
15a90 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
15aa0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15ab0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15ac0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
15ad0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
15ae0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15af0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
15b00 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15b10 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
15b20 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
15b30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15b40 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
15b50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15b60 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
15b70 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
15b80 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
15b90 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
15ba0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
15bb0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
15bc0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
15bd0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
15be0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
15bf0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
15c00 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
15c10 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
15c20 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
15c30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
15c40 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
15c50 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
15c60 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
15c70 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
15c80 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
15c90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
15ca0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
15cb0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
15cc0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
15cd0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
15ce0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
15cf0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
15d00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
15d10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15d20 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
15d30 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
15d40 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
15d50 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
15d60 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
15d70 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
15d80 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
15d90 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
15da0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15db0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
15dc0 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
15dd0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
15de0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
15df0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
15e00 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
15e10 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
15e20 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
15e30 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
15e40 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
15e50 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
15e60 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
15e70 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
15e80 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
15e90 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
15ea0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
15eb0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
15ec0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
15ed0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
15ee0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
15ef0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
15f00 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
15f10 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
15f20 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
15f30 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
15f40 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
15f50 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
15f60 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
15f70 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
15f80 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
15f90 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
15fa0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
15fb0 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48  :.** [H12281] [H
15fc0 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20  12282] [H12283] 
15fd0 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35  [H12284] [H12285
15fe0 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32  ] [H12287] [H122
15ff0 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20  88] [H12289].** 
16000 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49  [H12290].*/.SQLI
16010 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
16020 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
16030 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
16040 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
16050 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
16060 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
16070 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
16080 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
16090 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
160a0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
160b0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
160c0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
160d0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
160e0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
160f0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
16100 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36  cks {H12910} <S6
16110 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0400>.**.** This
16120 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
16130 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
16140 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
16150 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
16160 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
16170 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
16180 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
16190 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
161a0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
161b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
161c0 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
161d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
161e0 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
161f0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
16200 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
16210 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
16220 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
16230 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66   query..**.** If
16240 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
16250 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
16260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
16270 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
16280 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
16290 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
162a0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
162b0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
162c0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
162d0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
162e0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
162f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
16300 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
16310 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
16320 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
16330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16340 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
16350 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
16360 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
16370 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16380 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
16390 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
163a0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
163b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
163c0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
163d0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
163e0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
163f0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  aph..**.** Requi
16400 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
16410 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48  911] [H12912] [H
16420 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20  12913] [H12914] 
16430 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36  [H12915] [H12916
16440 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39  ] [H12917] [H129
16450 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  18].**.*/.void s
16460 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
16470 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
16480 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
16490 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
164a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
164b0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
164c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
164d0 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30   {H12700} <S4020
164e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
164f0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
16500 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
16510 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
16520 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
16530 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
16540 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61  ment. The filena
16550 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
16560 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
16570 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
16580 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
16590 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
165a0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
165b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
165c0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
165d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
165e0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
165f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
16600 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
16610 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
16620 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
16630 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
16640 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
16650 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
16660 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
16670 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
16680 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
16690 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
166a0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
166b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
166c0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
166d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
166e0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
166f0 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  t. If the databa
16700 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
16710 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
16720 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
16730 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
16740 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
16750 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
16760 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
16770 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
16780 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
16790 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
167a0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
167b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
167c0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
167d0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
167e0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
167f0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
16800 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
16810 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
16820 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
16830 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
16840 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
16850 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
16860 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
16870 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
16880 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
16890 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
168a0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
168b0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
168c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
168d0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
168e0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
168f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
16900 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16910 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
16920 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
16930 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
16940 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
16950 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
16960 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
16970 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
16980 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
16990 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
169a0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
169b0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
169c0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
169d0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
169e0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
169f0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
16a00 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
16a10 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
16a20 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
16a30 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
16a40 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
16a50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
16a60 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
16a70 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
16a80 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
16a90 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
16aa0 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
16ab0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
16ac0 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ags:.**.** <dl>.
16ad0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
16ae0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
16af0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
16b00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16b10 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
16b20 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
16b30 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
16b40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
16b50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
16b60 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
16b70 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
16b80 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
16b90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
16ba0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
16bb0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
16bc0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
16bd0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
16be0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
16bf0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
16c00 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
16c10 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
16c20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
16c30 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
16c40 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
16c50 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
16c60 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
16c70 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
16c80 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
16c90 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
16ca0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
16cb0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
16cc0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
16cd0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
16ce0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
16cf0 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
16d00 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
16d10 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
16d20 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
16d30 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
16d40 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
16d50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
16d60 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
16d70 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
16d80 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
16d90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
16da0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
16db0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
16dc0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
16dd0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
16de0 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
16df0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
16e00 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
16e10 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
16e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
16e30 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
16e40 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
16e50 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  lags,.** then th
16e60 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
16e70 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
16e80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
16e90 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
16ea0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
16eb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16ec0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
16ed0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
16ee0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
16ef0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
16f00 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
16f10 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
16f20 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
16f30 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
16f40 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65  rt-time.  If the
16f50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
16f60 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
16f70 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
16f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16f90 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
16fa0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
16fb0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
16fc0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
16fd0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
16fe0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
16ff0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
17000 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
17010 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
17020 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
17030 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
17040 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
17050 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
17060 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
17070 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
17080 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
17090 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
170a0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
170b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
170c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
170d0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
170e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
170f0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
17100 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
17110 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
17120 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
17130 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
17140 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
17150 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
17160 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
17170 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
17180 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
17190 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
171a0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
171b0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
171c0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
171d0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
171e0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
171f0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
17200 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
17210 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
17220 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
17230 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
17240 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
17250 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
17260 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
17270 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
17280 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
17290 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
172a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
172b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
172c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
172d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
172e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
172f0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
17300 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
17310 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
17320 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
17330 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
17340 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
17350 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
17360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17370 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
17380 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17390 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
173a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
173b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
173c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
173d0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
173e0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
173f0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
17400 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
17410 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
17420 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
17430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
17440 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
17450 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
17460 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
17470 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
17480 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
17490 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
174a0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
174b0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
174c0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
174d0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
174e0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
174f0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
17500 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
17510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17520 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  )..**.** Require
17530 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30  ments:.** [H1270
17540 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32  1] [H12702] [H12
17550 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48  703] [H12704] [H
17560 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20  12706] [H12707] 
17570 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31  [H12709] [H12711
17580 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48  ].** [H12712] [H
17590 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20  12713] [H12714] 
175a0 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39  [H12717] [H12719
175b0 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37  ] [H12721] [H127
175c0 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  23].*/.int sqlit
175d0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
175e0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
175f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17600 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
17610 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
17620 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
17630 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17640 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
17650 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
17660 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
17670 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17680 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17690 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
176a0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
176b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
176c0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
176d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
176e0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
176f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
17700 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17710 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
17720 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
17730 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
17740 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
17750 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
17760 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
17770 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
17780 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
17790 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
177a0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
177b0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
177c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
177d0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
177e0 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
177f0 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
17800 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
17810 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
17820 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
17830 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
17840 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
17850 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
17860 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17870 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
17880 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
17890 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
178a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
178b0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
178c0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
178d0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
178e0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
178f0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
17900 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
17910 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
17920 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
17930 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
17940 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
17950 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
17960 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
17970 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
17980 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
17990 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
179a0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
179b0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
179c0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
179d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
179e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
179f0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
17a00 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
17a10 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
17a20 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
17a30 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
17a40 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
17a50 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
17a60 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
17a70 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
17a80 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
17a90 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
17aa0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
17ab0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
17ac0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
17ad0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
17ae0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
17af0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
17b00 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
17b10 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
17b20 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
17b30 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
17b40 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
17b50 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
17b60 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
17b70 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
17b80 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
17b90 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
17ba0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
17bb0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
17bc0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
17bd0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
17be0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17bf0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
17c00 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
17c10 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
17c20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
17c30 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
17c40 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
17c50 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
17c60 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
17c70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
17c80 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
17c90 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
17ca0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
17cb0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
17cc0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
17cd0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
17ce0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
17cf0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
17d10 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
17d20 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
17d30 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
17d40 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
17d50 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
17d60 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
17d70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
17d80 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
17d90 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
17da0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
17db0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
17dc0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
17dd0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
17de0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
17df0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
17e00 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
17e10 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
17e20 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
17e30 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
17e40 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
17e50 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
17e60 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
17e70 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
17e80 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
17e90 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
17ea0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
17eb0 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32  ** [H12801] [H12
17ec0 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48  802] [H12803] [H
17ed0 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20  12807] [H12808] 
17ee0 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12809].*/.int 
17ef0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
17f00 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
17f10 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
17f20 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
17f30 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
17f40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
17f50 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
17f60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
17f70 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
17f80 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17f90 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
17fa0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
17fb0 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
17fc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
17fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
17fe0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
17ff0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
18000 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
18010 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
18020 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
18030 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
18040 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
18050 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
18060 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
18070 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
18080 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
18090 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
180a0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
180b0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
180c0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
180d0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
180e0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
180f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
18100 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
18110 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
18120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18130 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
18140 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
18150 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
18160 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
18170 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
18180 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
18190 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
181a0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
181b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
181c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
181d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
181e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
181f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
18200 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
18210 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
18220 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
18230 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
18240 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
18250 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
18260 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
18270 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
18280 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
18290 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
182a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
182b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
182c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
182d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
182e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
182f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
18300 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
18310 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
18320 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
18330 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
18340 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
18350 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
18360 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
18370 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
18380 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
18390 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
183a0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
183b0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
183c0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
183d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
183e0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
183f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
18400 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
18410 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
18420 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
18430 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
18440 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
18450 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
18460 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
18470 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
18480 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
18490 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
184a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
184b0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
184c0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
184d0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
184e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
184f0 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
18500 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
18510 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
18520 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
18530 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
18540 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
18550 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
18560 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
18570 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
18580 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
18590 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
185a0 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
185b0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
185c0 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
185d0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
185e0 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
185f0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
18600 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
18610 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
18620 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
18630 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
18640 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
18650 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
18660 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
18670 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
18680 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
18690 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
186a0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
186b0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
186c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
186d0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
186e0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
186f0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
18700 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
18710 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
18720 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
18730 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
18740 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
18750 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
18760 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
18770 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
18780 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
18790 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
187a0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
187b0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
187c0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
187d0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
187e0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
187f0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
18800 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
18810 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
18820 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
18830 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
18840 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
18850 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
18860 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
18870 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
18880 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
18890 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
188a0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
188b0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
188c0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
188d0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
188e0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
188f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18900 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
18910 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
18920 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
18930 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
18940 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
18950 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
18960 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
18970 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
18980 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
18990 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
189a0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
189b0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
189c0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
189d0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
189e0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
189f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
18a00 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48  :.** [H12762] [H
18a10 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a  12766] [H12769].
18a20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
18a30 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
18a40 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
18a50 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18a60 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
18a70 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
18a80 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e  H12790} <H12760>
18a90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
18aa0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
18ab0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
18ac0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
18ad0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
18ae0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
18af0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
18b00 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
18b10 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
18b20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
18b30 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
18b40 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
18b50 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
18b60 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
18b70 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
18b80 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
18b90 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
18ba0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
18bb0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
18bc0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
18bd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18be0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
18bf0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18c00 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
18c10 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
18c20 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
18c30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18c40 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
18c50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18c60 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
18c70 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
18c80 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
18c90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18ca0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
18cb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18cc0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
18cd0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
18ce0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
18cf0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
18d00 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
18d10 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
18d20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
18d30 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
18d40 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
18d50 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
18d60 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
18d70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
18d80 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
18d90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18da0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
18db0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
18dc0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
18dd0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18de0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
18df0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
18e00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
18e10 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
18e20 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
18e30 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
18e40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18e50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
18e60 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
18e70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
18e80 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
18e90 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
18ea0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
18eb0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
18ec0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
18ed0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
18ee0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18ef0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
18f00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18f10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
18f20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
18f30 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
18f40 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18f50 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
18f60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18f70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
18f80 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
18f90 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
18fa0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18fb0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
18fc0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
18fd0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
18fe0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
18ff0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
19000 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
19010 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
19020 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
19030 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19040 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
19050 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
19060 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
19070 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
19080 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
19090 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
190a0 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
190b0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
190c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
190d0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
190e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
190f0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
19100 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
19110 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
19120 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
19130 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
19140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19150 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
19160 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
19170 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
19180 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
19190 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
191a0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
191b0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
191c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
191d0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
191e0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
191f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
19200 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
19210 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
19220 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
19230 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
19240 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
19250 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
19260 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
19270 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
19280 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
19290 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
192a0 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
192b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
192c0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
192d0 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
192e0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
192f0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
19300 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
19310 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
19320 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
19330 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
19340 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
19350 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
19360 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
19370 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
19380 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19390 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
193a0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
193b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
193c0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
193d0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
193e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
193f0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19400 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
19410 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
19420 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
19430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19440 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
19450 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
19460 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
19470 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
19480 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
19490 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
194a0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
194b0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
194c0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
194d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
194e0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
194f0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
19500 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
19510 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19520 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
19530 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
19540 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
19550 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
19560 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
19570 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
19580 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
19590 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
195a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
195b0 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20  nator. If nByte 
195c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
195d0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
195e0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
195f0 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
19600 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
19610 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
19620 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
19630 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
19640 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
19650 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
19660 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
19670 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
19680 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
19690 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
196a0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
196b0 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
196c0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
196d0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
196e0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
196f0 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
19700 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
19710 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
19720 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
19730 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
19740 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
19750 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
19760 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
19770 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
19780 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
19790 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
197a0 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  r bytes..**.** I
197b0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
197c0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
197d0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
197e0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
197f0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
19800 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
19810 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
19820 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
19830 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
19840 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
19850 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
19860 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
19870 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
19880 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
19890 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
198a0 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
198b0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
198c0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
198d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
198e0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
198f0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
19900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19910 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
19920 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
19930 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
19940 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
19950 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19960 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
19970 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
19980 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
19990 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
199a0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
199b0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
199c0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
199d0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
199e0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
199f0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
19a00 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
19a10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
19a20 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
19a30 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
19a40 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
19a50 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
19a60 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
19a70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
19a80 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
19a90 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
19aa0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
19ab0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19ac0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
19ad0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
19ae0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
19af0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
19b00 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
19b10 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
19b20 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
19b30 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
19b40 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
19b50 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19b60 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
19b70 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
19b80 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
19b90 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
19ba0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19bb0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
19bc0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
19bd0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
19be0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
19bf0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
19c00 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
19c10 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
19c20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19c30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
19c40 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
19c50 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
19c60 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
19c70 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
19c80 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
19c90 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
19ca0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
19cb0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19cc0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
19cd0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
19ce0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19cf0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
19d00 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
19d10 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
19d20 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
19d30 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
19d40 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
19d50 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
19d60 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
19d70 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
19d80 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
19d90 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
19da0 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
19db0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
19dc0 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
19dd0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
19de0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
19df0 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74   is.** now a fat
19e00 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
19e10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
19e20 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
19e30 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
19e40 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
19e50 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
19e60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
19e70 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
19e80 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
19e90 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
19ea0 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
19eb0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
19ec0 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  turn..** </li>.*
19ed0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
19ee0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
19ef0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
19f00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
19f10 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
19f20 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
19f30 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
19f40 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
19f50 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   The legacy beha
19f60 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
19f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19f80 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
19f90 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
19fa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
19fb0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
19fc0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
19fd0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
19fe0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
19ff0 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64  _reset()] in ord
1a000 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68  er.** to find th
1a010 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1a020 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1a030 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1a040 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1a050 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1a060 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1a070 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1a080 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1a090 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1a0a0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71   </ol>.**.** Req
1a0b0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1a0c0 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20  13011] [H13012] 
1a0d0 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34  [H13013] [H13014
1a0e0 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30  ] [H13015] [H130
1a0f0 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31  16] [H13019] [H1
1a100 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20  3021].**.*/.int 
1a110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1a120 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a140 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a150 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1a160 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a170 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a180 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1a190 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1a1a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1a1b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1a1c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1a1d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1a1e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1a1f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1a200 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a210 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1a220 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1a230 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1a240 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1a250 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1a260 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1a270 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a280 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a290 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1a2a0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1a2b0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a2c0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1a2d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a2f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a300 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a310 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a320 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1a330 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1a340 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a350 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1a360 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1a370 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1a380 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1a390 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1a3a0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1a3b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a3c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a3d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a3e0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1a3f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a400 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1a410 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a420 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a430 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a440 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a450 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a460 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a470 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a480 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1a4a0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a4b0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a4c0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a4d0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1a4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a4f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1a500 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1a510 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1a520 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1a530 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1a540 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1a550 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1a560 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a570 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a580 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a590 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a5a0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a5b0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a5c0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a5d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a5e0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1a5f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a600 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a610 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a620 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1a630 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1a640 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48  Statement SQL {H
1a650 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a  13100} <H13000>.
1a660 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1a670 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1a680 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1a690 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1a6a0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1a6b0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1a6c0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1a6d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1a6e0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1a6f0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1a700 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1a710 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a720 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1a730 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1a740 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1a750 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b  s:.** [H13101] [
1a760 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d  H13102] [H13103]
1a770 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1a780 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1a790 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1a7a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a7b0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1a7c0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1a7d0 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
1a7e0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1a7f0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1a800 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1a810 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a820 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1a830 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1a840 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1a850 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1a860 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1a870 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1a880 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1a890 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1a8a0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1a8b0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1a8c0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
1a8d0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1a8e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a8f0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1a900 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1a910 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1a920 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1a930 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1a940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1a950 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1a960 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1a970 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1a980 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1a990 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1a9a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a9b0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1a9c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1a9d0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1a9e0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1a9f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1aa00 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1aa10 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1aa20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1aa30 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1aa40 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1aa50 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1aa60 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1aa70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1aa80 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1aa90 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1aaa0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1aab0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1aac0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1aad0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1aae0 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1aaf0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1ab00 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1ab10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ab20 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1ab30 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1ab40 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1ab50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ab60 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1ab70 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1ab80 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1ab90 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1aba0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1abb0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1abc0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1abd0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1abe0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1abf0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1ac00 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1ac10 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1ac20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1ac30 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1ac40 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1ac50 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1ac60 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1ac70 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1ac80 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1ac90 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1aca0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1acb0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1acc0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1acd0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1ace0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1acf0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1ad00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ad10 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1ad20 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1ad30 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1ad40 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1ad50 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ad60 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1ad70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ad80 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1ad90 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1ada0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1adb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1adc0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1add0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1ade0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1adf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ae00 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1ae10 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1ae20 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1ae30 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1ae40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1ae50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1ae60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1ae70 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1ae80 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1ae90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1aea0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1aeb0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1aec0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1aed0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1aee0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1aef0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1af00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1af10 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1af20 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1af30 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1af40 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1af50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1af60 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1af70 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1af80 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1af90 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1afa0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1afb0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1afc0 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
1afd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
1afe0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1aff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1b000 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1b010 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1b020 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1b030 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1b040 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1b050 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1b060 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1b070 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1b080 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1b090 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1b0a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1b0b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1b0c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1b0d0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1b0e0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1b0f0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1b100 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1b110 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1b120 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1b130 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1b140 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1b150 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1b160 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1b170 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1b180 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1b190 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1b1a0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1b1b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1b1c0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1b1d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1b1e0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1b1f0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1b200 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1b210 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1b220 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1b230 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
1b240 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1b250 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1b260 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1b270 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1b280 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1b290 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1b2a0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1b2b0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1b2c0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
1b2d0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1b2e0 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1b2f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b300 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1b310 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1b320 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1b330 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1b340 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
1b350 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
1b360 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1b370 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1b380 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1b390 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1b3a0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1b3b0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
1b3c0 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
1b3d0 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
1b3e0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1b3f0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
1b400 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
1b410 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
1b420 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
1b430 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1b440 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1b450 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1b460 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1b470 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1b480 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1b490 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1b4a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1b4b0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1b4c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1b4d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1b4e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1b4f0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1b500 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1b510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1b520 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1b530 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1b540 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b550 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1b560 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
1b570 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1b580 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1b590 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1b5a0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
1b5b0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1b5c0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1b5d0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
1b5e0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
1b5f0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1b600 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
1b610 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
1b620 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
1b630 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
1b640 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
1b650 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
1b660 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
1b670 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
1b680 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
1b690 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
1b6a0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
1b6b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b6c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
1b6d0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1b6e0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1b6f0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1b700 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1b710 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1b720 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1b730 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1b740 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1b750 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
1b760 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
1b770 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
1b780 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1b790 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1b7a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1b7b0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1b7c0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1b7d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1b7e0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1b7f0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1b800 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1b810 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1b820 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1b830 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1b840 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1b850 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1b860 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1b870 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1b880 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1b890 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1b8a0 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
1b8b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1b8c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1b8d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1b8e0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1b8f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1b900 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1b910 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1b930 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1b940 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1b950 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1b960 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1b970 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1b980 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1b990 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1b9a0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1b9b0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1b9c0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1b9d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1b9e0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1b9f0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1ba00 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1ba10 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1ba20 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1ba30 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1ba40 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1ba50 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1ba60 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1ba70 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1ba80 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1ba90 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1baa0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1bab0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1bac0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1bad0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1bae0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1baf0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1bb00 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1bb10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1bb20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1bb30 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1bb40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1bb50 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1bb60 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1bb70 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1bb80 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1bb90 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
1bba0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1bbb0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1bbc0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1bbd0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1bbe0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1bbf0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1bc00 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1bc10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1bc20 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1bc30 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1bc40 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1bc50 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1bc60 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1bc70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1bc80 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1bc90 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1bca0 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
1bcb0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1bcc0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1bcd0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1bce0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1bcf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1bd00 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1bd10 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1bd20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1bd30 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1bd40 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1bd50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1bd60 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1bd70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1bd80 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1bd90 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1bda0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1bdb0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1bdc0 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1bdd0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1bde0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1bdf0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1be00 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1be10 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1be20 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1be30 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1be40 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1be50 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1be60 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1be70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1be80 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1be90 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1bea0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1beb0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1bec0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1bed0 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1bee0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1bef0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1bf00 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1bf10 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1bf20 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1bf30 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1bf40 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1bf50 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1bf60 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1bf70 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1bf80 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1bf90 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1bfa0 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1bfb0 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1bfc0 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1bfd0 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1bfe0 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1bff0 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1c000 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1c010 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1c020 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1c030 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1c040 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1c050 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1c060 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1c070 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1c080 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1c090 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c0a0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1c0b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c0c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1c0d0 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
1c0e0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30  ments:.** [H1350
1c0f0 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33  6] [H13509] [H13
1c100 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48  512] [H13515] [H
1c110 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20  13518] [H13521] 
1c120 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37  [H13524] [H13527
1c130 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48  ].** [H13530] [H
1c140 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20  13533] [H13536] 
1c150 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32  [H13539] [H13542
1c160 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35  ] [H13545] [H135
1c170 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a  48] [H13551].**.
1c180 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c190 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1c1a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1c1b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1c1c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1c1d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c1e0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1c1f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1c200 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1c210 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1c220 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c230 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1c240 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1c250 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c260 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1c270 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c280 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1c290 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1c2a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c2b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1c2c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1c2d0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1c2e0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c2f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c300 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1c310 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1c320 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1c330 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1c340 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1c350 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c360 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1c370 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1c380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1c390 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1c3a0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1c3b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c3c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1c3d0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
1c3e0 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
1c3f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c400 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1c410 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1c420 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1c430 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1c440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c450 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1c460 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1c470 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1c480 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1c490 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1c4a0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1c4b0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1c4c0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1c4d0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1c4e0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1c4f0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1c500 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1c510 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
1c520 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
1c530 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
1c540 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
1c550 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
1c560 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
1c570 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1c580 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1c590 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1c5a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1c5b0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
1c5c0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1c5d0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1c5e0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
1c5f0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
1c600 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1c610 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1c620 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1c630 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1c640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1c650 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1c660 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1c670 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c680 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1c690 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1c6a0 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a  .** [H13601].*/.
1c6b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1c6c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1c6d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1c6e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c6f0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1c700 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
1c710 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
1c720 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1c730 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c740 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1c750 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
1c760 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
1c770 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1c780 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1c790 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1c7a0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1c7b0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1c7c0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1c7d0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1c7e0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1c7f0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1c800 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1c810 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1c820 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1c830 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1c840 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1c850 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1c860 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1c870 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1c880 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1c890 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1c8a0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1c8b0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1c8c0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1c8d0 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
1c8e0 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
1c8f0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
1c900 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
1c910 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1c920 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1c930 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
1c940 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
1c950 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1c960 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
1c970 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1c980 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1c990 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1c9a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1c9b0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
1c9c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c9d0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
1c9e0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
1c9f0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
1ca00 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
1ca10 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
1ca20 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
1ca30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ca40 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ca50 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1ca60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1ca70 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1ca80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ca90 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1caa0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1cab0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1cac0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1cad0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1cae0 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a  .** [H13621].*/.
1caf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1cb00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1cb10 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
1cb20 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
1cb30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1cb40 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
1cb50 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
1cb60 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
1cb70 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
1cb80 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1cb90 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1cba0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1cbb0 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1cbc0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1cbd0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1cbe0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1cbf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1cc00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1cc10 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1cc20 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1cc30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1cc40 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1cc50 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1cc60 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1cc70 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1cc80 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1cc90 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1cca0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1ccb0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1ccc0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1ccd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1cce0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1ccf0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1cd00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1cd10 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1cd20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1cd30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1cd40 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1cd50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1cd60 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1cd70 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1cd80 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a  s:.** [H13641].*
1cd90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1cda0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1cdb0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
1cdc0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1cdd0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
1cde0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
1cdf0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
1ce00 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1ce10 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
1ce20 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
1ce30 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1ce40 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1ce50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1ce60 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
1ce70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1ce80 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1ce90 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
1cea0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1ceb0 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
1cec0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
1ced0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1cee0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52  to NULL..**.** R
1cef0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1cf00 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13661].*/.int 
1cf10 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
1cf20 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
1cf30 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1cf40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1cf50 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
1cf60 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31  esult Set {H1371
1cf70 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1cf80 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
1cf90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1cfa0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1cfb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1cfc0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1cfd0 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
1cfe0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
1cff0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1d000 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d010 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
1d020 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
1d030 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
1d040 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  TE])..**.** Requ
1d050 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1d060 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3711].*/.int sql
1d070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
1d080 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1d090 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1d0a0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
1d0b0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
1d0c0 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
1d0d0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1d0e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d0f0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1d100 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1d110 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1d120 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1d130 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1d140 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
1d150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d160 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
1d170 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1d180 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1d190 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1d1a0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
1d1b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1d1c0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
1d1d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
1d1e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d1f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
1d200 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d210 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
1d220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
1d230 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
1d240 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
1d250 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
1d260 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d270 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
1d280 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1d290 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
1d2a0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1d2b0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1d2c0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
1d2d0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
1d2e0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
1d2f0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
1d300 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
1d310 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d320 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1d330 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
1d340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d350 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1d360 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1d370 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
1d380 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
1d390 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d3a0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
1d3b0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
1d3c0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
1d3d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
1d3e0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
1d3f0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
1d400 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
1d410 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d420 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1d430 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
1d440 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
1d450 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1d460 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
1d470 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
1d480 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
1d490 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
1d4a0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
1d4b0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
1d4c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
1d4d0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
1d4e0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
1d4f0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
1d500 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
1d510 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
1d520 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1d530 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48  :.** [H13721] [H
1d540 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20  13723] [H13724] 
1d550 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36  [H13725] [H13726
1d560 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f  ] [H13727].*/.co
1d570 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d580 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1d590 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d5a0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1d5b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1d5c0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1d5d0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1d5e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d5f0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1d600 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1d610 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30  {H13740} <S10700
1d620 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1d630 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1d640 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1d650 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
1d660 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
1d670 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
1d680 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
1d690 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1d6a0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
1d6b0 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
1d6c0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
1d6d0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
1d6e0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
1d6f0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
1d700 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
1d710 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
1d720 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
1d730 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
1d740 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
1d750 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
1d760 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
1d770 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
1d780 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
1d790 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
1d7a0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
1d7b0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1d7c0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
1d7d0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
1d7e0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1d7f0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
1d800 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1d810 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
1d820 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
1d830 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
1d840 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
1d850 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
1d860 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
1d870 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
1d880 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
1d890 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
1d8a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d8b0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
1d8c0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
1d8d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d8e0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
1d8f0 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
1d900 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1d910 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1d920 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
1d930 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
1d940 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1d950 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
1d960 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
1d970 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
1d980 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
1d990 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
1d9a0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1d9b0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1d9c0 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1d9d0 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
1d9e0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1d9f0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1da00 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1da10 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1da20 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
1da30 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
1da40 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
1da50 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
1da60 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
1da70 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
1da80 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
1da90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1daa0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1dab0 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
1dac0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1dad0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
1dae0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1daf0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1db00 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1db10 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1db20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1db30 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1db40 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1db50 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1db60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1db70 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1db80 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1db90 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1dba0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1dbb0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1dbc0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
1dbd0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1dbe0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
1dbf0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1dc00 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1dc10 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  A13751}.** If tw
1dc20 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1dc30 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1dc40 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1dc50 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1dc60 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1dc70 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1dc80 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1dc90 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1dca0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1dcb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1dcc0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1dcd0 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37  * [H13741] [H137
1dce0 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31  42] [H13743] [H1
1dcf0 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b  3744] [H13745] [
1dd00 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d  H13746] [H13748]
1dd10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
1dd20 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1dd30 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
1dd40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1dd50 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
1dd60 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
1dd70 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
1dd80 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
1dd90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dda0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
1ddb0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
1ddc0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1ddd0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1dde0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
1ddf0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1de00 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1de10 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1de20 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1de30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1de40 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1de50 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1de60 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
1de70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1de80 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
1de90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1dea0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1deb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1dec0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
1ded0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1dee0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1def0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
1df00 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1df10 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1df20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1df30 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
1df40 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1df50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1df60 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
1df70 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
1df80 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1df90 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
1dfa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1dfb0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
1dfc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1dfd0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
1dfe0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
1dff0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
1e000 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
1e010 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
1e020 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
1e030 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
1e040 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
1e050 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
1e060 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1e070 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
1e080 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
1e090 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
1e0a0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
1e0b0 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
1e0c0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1e0d0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
1e0e0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1e0f0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
1e100 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1e110 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
1e120 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1e130 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
1e140 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
1e150 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1e160 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
1e170 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1e180 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1e190 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1e1a0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
1e1b0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1e1c0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
1e1d0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
1e1e0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
1e1f0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
1e200 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
1e210 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
1e220 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
1e230 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
1e240 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
1e250 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
1e260 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
1e270 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
1e280 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e290 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e2a0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e2b0 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e2c0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e2d0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e2e0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e2f0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e300 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e310 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e320 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e330 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e340 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e350 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e360 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e370 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e380 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e390 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1e3a0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1e3b0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1e3c0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1e3d0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1e3e0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1e3f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1e400 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48  :.** [H13761] [H
1e410 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a  13762] [H13763].
1e420 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1e440 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
1e450 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1e470 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1e480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e490 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1e4a0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
1e4b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1e4c0 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30  {H13200} <S10000
1e4d0 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  >.**.** After a 
1e4e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e4f0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
1e500 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
1e510 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
1e520 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e540 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
1e550 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
1e560 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
1e570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e580 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1e590 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
1e5a0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
1e5b0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
1e5c0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1e5d0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
1e5e0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
1e5f0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
1e600 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
1e610 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e620 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
1e630 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
1e640 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
1e650 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1e660 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
1e670 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
1e680 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e690 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e6a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1e6b0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
1e6c0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1e6d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e6e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1e6f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
1e700 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
1e710 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
1e720 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1e730 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
1e740 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
1e750 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1e760 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
1e770 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
1e780 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
1e790 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1e7a0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
1e7b0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
1e7c0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
1e7d0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
1e7e0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
1e7f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
1e800 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
1e810 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  SUSE]..** With t
1e820 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1e830 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
1e840 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
1e850 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
1e860 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1e870 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1e880 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
1e890 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1e8a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1e8b0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1e8c0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1e8d0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1e8e0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1e8f0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1e900 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1e910 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
1e920 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
1e930 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
1e940 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1e950 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
1e960 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
1e970 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
1e980 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
1e990 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
1e9a0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1e9b0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
1e9c0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
1e9d0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
1e9e0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
1e9f0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
1ea00 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53  inuing..**.** [S
1ea10 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
1ea20 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
1ea30 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
1ea40 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
1ea50 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
1ea60 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1ea70 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1ea80 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
1ea90 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
1eaa0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
1eab0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1eac0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
1ead0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
1eae0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
1eaf0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
1eb00 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tate..**.** If t
1eb10 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1eb20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
1eb30 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
1eb40 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
1eb50 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
1eb60 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
1eb70 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
1eb80 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
1eb90 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
1eba0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
1ebb0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
1ebc0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
1ebd0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1ebe0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
1ebf0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
1ec00 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
1ec10 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
1ec20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
1ec30 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1ec40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
1ec50 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
1ec60 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
1ec70 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
1ec80 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
1ec90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1eca0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1ecb0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
1ecc0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
1ecd0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
1ece0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
1ecf0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
1ed00 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
1ed10 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
1ed20 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
1ed30 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
1ed40 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
1ed50 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1ed60 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
1ed70 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
1ed80 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
1ed90 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
1eda0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
1edb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1edc0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
1edd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ede0 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
1edf0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
1ee00 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1ee10 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
1ee20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
1ee30 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
1ee40 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
1ee50 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
1ee60 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
1ee70 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
1ee80 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
1ee90 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
1eea0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
1eeb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1eec0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
1eed0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
1eee0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1eef0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
1ef00 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
1ef10 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
1ef20 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
1ef30 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
1ef40 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
1ef50 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
1ef60 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
1ef70 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1ef80 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
1ef90 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
1efa0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
1efb0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
1efc0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
1efd0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
1efe0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
1eff0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
1f000 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
1f010 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
1f020 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
1f030 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
1f040 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
1f050 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
1f060 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
1f070 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f080 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
1f090 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
1f0a0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
1f0b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f0c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1f0d0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
1f0e0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
1f0f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1f100 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
1f110 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
1f120 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
1f130 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
1f140 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
1f150 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
1f160 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
1f170 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
1f180 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
1f190 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
1f1a0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
1f1b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
1f1c0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f1d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f1e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1f1f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
1f200 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
1f210 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
1f220 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
1f230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f240 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
1f250 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
1f260 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1f270 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1f280 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1f290 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1f2a0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1f2b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f2c0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f2d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
1f2e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32  ements:.** [H132
1f2f0 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31  02] [H15304] [H1
1f300 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b  5306] [H15308] [
1f310 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H15310].*/.int s
1f320 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
1f330 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1f350 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1f360 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
1f370 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
1f380 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
1f390 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
1f3a0 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
1f3b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
1f3c0 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
1f3d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1f3e0 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37   [H13771] [H1377
1f3f0 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
1f400 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
1f410 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1f420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f430 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
1f440 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
1f450 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
1f460 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
1f470 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
1f480 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
1f490 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
1f4a0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
1f4b0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
1f4c0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
1f4d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
1f4e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f4f0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
1f500 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
1f510 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
1f520 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
1f530 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
1f540 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
1f550 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
1f560 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
1f570 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
1f580 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
1f590 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
1f5a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
1f5b0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
1f5c0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
1f5d0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
1f5e0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
1f5f0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
1f600 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
1f610 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
1f620 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
1f630 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
1f640 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
1f650 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
1f660 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
1f670 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
1f680 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
1f690 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1f6a0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
1f6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
1f6c0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
1f6d0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
1f6e0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
1f6f0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
1f700 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
1f710 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
1f720 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
1f730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
1f740 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
1f750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1f760 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
1f770 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
1f780 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
1f790 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
1f7a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
1f7b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1f7c0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
1f7d0 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
1f7e0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
1f7f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f800 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
1f810 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
1f820 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
1f830 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
1f840 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
1f850 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
1f860 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
1f870 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
1f880 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
1f890 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f8a0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
1f8b0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
1f8c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
1f8d0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
1f8e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1f8f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f900 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1f910 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
1f920 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1f930 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1f940 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
1f950 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
1f960 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
1f970 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1f980 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
1f990 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1f9a0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
1f9b0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
1f9c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
1f9d0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
1f9e0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
1f9f0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
1fa00 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
1fa10 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1fa20 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
1fa30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
1fa40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
1fa50 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1fa60 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
1fa70 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
1fa80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fa90 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
1faa0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
1fab0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
1fac0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
1fad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1fae0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
1faf0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
1fb00 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
1fb10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1fb20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
1fb30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fb40 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1fb50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1fb60 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
1fb70 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
1fb80 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
1fb90 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
1fba0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
1fbb0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
1fbc0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
1fbd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
1fbe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1fbf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
1fc00 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
1fc10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
1fc20 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
1fc30 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
1fc40 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
1fc50 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
1fc60 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
1fc70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1fc80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
1fc90 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
1fca0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
1fcb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
1fcc0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
1fcd0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
1fce0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
1fcf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
1fd00 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
1fd10 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
1fd20 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
1fd30 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
1fd40 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
1fd50 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
1fd60 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
1fd70 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
1fd80 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1fd90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
1fda0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
1fdb0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
1fdc0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
1fdd0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
1fde0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
1fdf0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
1fe00 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
1fe10 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
1fe20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1fe30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
1fe40 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
1fe50 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
1fe60 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
1fe70 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
1fe80 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
1fe90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
1fea0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
1feb0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
1fec0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
1fed0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
1fee0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
1fef0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
1ff00 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
1ff10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1ff20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1ff30 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
1ff40 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
1ff50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
1ff60 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
1ff70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
1ff80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
1ff90 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
1ffa0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
1ffb0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
1ffc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1ffd0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
1ffe0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
1fff0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
20000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20010 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
20020 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
20030 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
20040 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
20050 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
20060 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
20070 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
20080 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
20090 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
200a0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
200b0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
200c0 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
200d0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
200e0 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
200f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
20100 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
20110 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
20120 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
20130 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
20140 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
20150 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
20160 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
20170 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
20180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20190 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
201a0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
201b0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
201c0 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
201d0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
201e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
201f0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
20200 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
20210 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
20220 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
20230 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
20240 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
20250 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
20260 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
20270 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
20280 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
20290 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
202a0 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
202b0 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
202c0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
202d0 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
202e0 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
202f0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
20300 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
20310 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
20320 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
20330 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
20340 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
20350 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
20360 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20370 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
20380 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
20390 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
203a0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
203b0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
203c0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
203d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
203e0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
203f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
20400 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20410 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
20420 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
20430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
20440 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
20450 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
20460 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
20470 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
20480 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
20490 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
204a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
204b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
204c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
204d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
204e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
204f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
20500 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
20510 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
20520 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
20530 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
20540 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
20550 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
20560 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
20570 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
20580 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
20590 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
205a0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
205b0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
205c0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
205d0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
205e0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
205f0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
20600 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
20610 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
20620 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
20630 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
20640 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
20650 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
20660 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
20670 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
20680 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
20690 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
206a0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
206b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
206c0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
206d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
206e0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
206f0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
20700 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
20710 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20720 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
20730 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20740 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20750 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20760 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20770 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
20780 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
20790 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
207a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
207b0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
207c0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
207d0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
207e0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
207f0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
20800 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
20810 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
20820 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
20830 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
20840 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
20850 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
20860 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
20870 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
20880 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
20890 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
208a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
208b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
208c0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
208d0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
208e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
208f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
20900 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
20910 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
20920 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
20930 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
20940 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
20950 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20960 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
20970 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
20980 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
20990 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
209a0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
209b0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
209c0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
209d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
209e0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
209f0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
20a00 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20a10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
20a20 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
20a30 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
20a40 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
20a50 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
20a60 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
20a70 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
20a80 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
20a90 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
20aa0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
20ab0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
20ac0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
20ad0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
20ae0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
20af0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
20b00 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
20b10 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
20b20 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
20b30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
20b40 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
20b50 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
20b60 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
20b70 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
20b80 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
20b90 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
20ba0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
20bb0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
20bc0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
20bd0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
20be0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
20bf0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
20c00 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
20c10 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
20c20 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
20c30 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
20c40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
20c50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20c60 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
20c70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
20c80 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
20c90 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
20ca0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
20cb0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
20cc0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
20cd0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
20ce0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
20cf0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
20d00 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
20d10 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
20d20 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
20d30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
20d40 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
20d50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
20d60 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
20d70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
20d80 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
20d90 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
20da0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
20db0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
20dc0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
20dd0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
20de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20df0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
20e00 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
20e10 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
20e20 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
20e30 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
20e40 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
20e50 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
20e60 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
20e70 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
20e80 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
20e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20ea0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
20eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20ec0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
20ed0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
20ee0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
20ef0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
20f00 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
20f10 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
20f20 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
20f30 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
20f40 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
20f50 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
20f60 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
20f70 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
20f80 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
20f90 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
20fa0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
20fb0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
20fc0 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
20fd0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
20fe0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
20ff0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
21000 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
21010 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
21020 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
21030 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
21040 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
21050 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
21060 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
21070 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
21080 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
21090 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
210a0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
210b0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
210c0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
210d0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
210e0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
210f0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
21100 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
21110 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
21120 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
21130 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21140 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
21150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
21160 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
21170 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21180 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
21190 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
211a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
211b0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
211c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
211d0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
211e0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
211f0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
21200 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
21210 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
21220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21230 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
21240 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
21250 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
21260 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
21270 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
21280 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
21290 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
212a0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
212b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
212c0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
212d0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
212e0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
212f0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
21300 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
21310 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
21320 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21330 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
21340 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
21350 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
21360 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
21370 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
21380 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
21390 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
213a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
213b0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
213c0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
213d0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
213e0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
213f0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
21400 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
21410 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
21420 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
21430 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21440 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21450 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
21460 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
21470 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
21480 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
21490 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
214a0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
214b0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
214c0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
214d0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
214e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
214f0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
21500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
21510 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
21520 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
21530 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
21540 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
21550 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
21560 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
21570 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21580 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
21590 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
215a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
215b0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
215c0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
215d0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
215e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
215f0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
21600 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
21610 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
21620 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
21630 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
21640 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
21650 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
21660 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
21670 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b  3803] [H13806] [
21680 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d  H13809] [H13812]
21690 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31   [H13815] [H1381
216a0 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33  8] [H13821] [H13
216b0 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d  824].** [H13827]
216c0 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e   [H13830].*/.con
216d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
216e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
216f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21700 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21730 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
21740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21750 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
21760 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
21770 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
21780 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
21790 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
217a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
217b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
217c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
217d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
217e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
217f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
21800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21810 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
21820 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
21830 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
21840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21850 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
21860 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21870 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
21880 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21890 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
218a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
218b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
218c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
218d0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
218e0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
218f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21910 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
21920 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
21930 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
21940 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
21950 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
21960 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
21970 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
21980 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
21990 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
219a0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
219b0 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
219c0 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
219d0 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
219e0 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
219f0 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
21a00 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
21a10 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
21a20 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
21a30 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
21a40 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
21a50 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
21a60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
21a70 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
21a80 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
21a90 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
21aa0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
21ab0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
21ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21ad0 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
21ae0 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
21af0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
21b00 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
21b10 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
21b20 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
21b30 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
21b40 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
21b50 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
21b60 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
21b70 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
21b80 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
21b90 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
21ba0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
21bb0 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
21bc0 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
21bd0 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
21be0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
21bf0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
21c00 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
21c10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
21c20 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20  ts:.** [H11302] 
21c30 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20  [H11304].*/.int 
21c40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21c50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
21c60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
21c70 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
21c80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
21c90 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33  nt Object {H1333
21ca0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
21cb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
21cc0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
21cd0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
21ce0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
21cf0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
21d00 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
21d10 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
21d20 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
21d30 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
21d40 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
21d50 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
21d60 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
21d70 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
21d80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21d90 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
21da0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
21db0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
21dc0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
21dd0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
21de0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
21df0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
21e00 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {H11332} The [sq
21e10 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
21e20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
21e30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21e40 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
21e50 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
21e60 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
21e70 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
21e80 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20  .** {H11334} If 
21e90 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21ea0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21eb0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
21ec0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
21ed0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21ee0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
21ef0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
21f00 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
21f10 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
21f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21f30 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
21f40 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
21f50 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
21f60 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
21f70 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
21f80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
21f90 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74  ** {H11336} If t
21fa0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
21fb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21fc0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
21fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
21fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21ff0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
22000 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
22010 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22020 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
22030 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
22040 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
22050 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20  .**.** {H11338} 
22060 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
22070 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
22080 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
22090 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
220a0 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
220b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
220c0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
220d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
220e0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
220f0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
22100 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22110 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22120 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
22130 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
22140 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d  nctions {H16100}
22150 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S20200>.** KEY
22160 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
22170 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
22180 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
22190 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
221a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
221b0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
221c0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
221d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
221e0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
221f0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
22200 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
22210 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
22220 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
22230 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
22240 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
22250 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
22260 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
22270 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
22280 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
22290 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
222a0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
222b0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
222c0 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
222d0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
222e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
222f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22300 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
22310 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
22320 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
22330 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
22340 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
22350 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
22360 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
22370 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
22380 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
22390 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
223a0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
223b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
223c0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
223d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
223e0 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73  e added.  If a s
223f0 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73  ingle program us
22400 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
22410 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
22420 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c  nection internal
22430 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e  ly, then SQL fun
22440 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
22450 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
22460 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74  y to.** each dat
22470 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
22490 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
224a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
224b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
224c0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
224d0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65   redefined.  The
224e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
224f0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
22500 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
22510 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65  lusive of.** the
22520 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
22530 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
22540 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d   name length lim
22550 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20  it is in bytes, 
22560 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  not.** character
22570 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  s.  Any attempt 
22580 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
22590 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
225a0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
225b0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
225c0 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72  E_ERROR] being r
225d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
225e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
225f0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
22600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
22610 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
22620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
22630 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
22640 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
22650 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
22660 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
22670 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
22680 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
22690 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
226a0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
226b0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
226c0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
226d0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
226e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
226f0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
22700 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
22710 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
22720 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
22730 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
22740 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
22750 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
22760 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
22770 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
22780 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
22790 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
227a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
227b0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
227c0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
227d0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
227e0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
227f0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
22800 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
22810 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
22820 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
22830 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
22840 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
22850 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
22860 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
22870 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
22880 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
22890 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
228a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
228b0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
228c0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
228d0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
228e0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
228f0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
22900 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
22910 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
22920 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
22930 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
22940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
22950 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
22960 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
22970 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
22980 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
22990 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
229a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
229b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
229c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
229d0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
229e0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
229f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
22a00 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
22a10 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
22a20 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
22a30 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
22a40 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
22a50 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
22a60 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
22a70 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
22a80 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
22a90 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
22aa0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
22ab0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
22ac0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
22ad0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
22ae0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
22af0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
22b00 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
22b10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
22b20 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
22b30 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
22b40 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
22b50 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
22b60 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
22b70 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
22b80 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
22b90 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
22ba0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
22bb0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
22bc0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
22bd0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
22be0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
22bf0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
22c00 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
22c10 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
22c20 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
22c30 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
22c40 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
22c50 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
22c60 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
22c70 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
22c80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
22c90 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
22ca0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
22cb0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
22cc0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
22cd0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
22ce0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
22cf0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
22d00 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
22d10 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
22d20 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
22d30 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
22d40 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
22d50 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
22d60 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
22d70 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66  on is used.  A f
22d80 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
22d90 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
22da0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
22db0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
22dc0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
22dd0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
22de0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
22df0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
22e00 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69   nArg.  A functi
22e10 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
22e20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
22e30 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
22e40 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
22e50 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
22e60 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
22e70 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
22e80 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
22e90 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
22ea0 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
22eb0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
22ec0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
22ed0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
22ee0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
22ef0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
22f00 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
22f10 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
22f20 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
22f30 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
22f40 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
22f50 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
22f60 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
22f70 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
22f80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22f90 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  functions..** Th
22fa0 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
22fb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
22fc0 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
22fd0 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
22fe0 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
22ff0 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
23000 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
23010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
23020 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
23030 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
23040 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23050 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
23060 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
23070 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
23080 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
23090 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
230a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
230b0 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
230c0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
230d0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
230e0 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
230f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70  ng..**.** An app
23100 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23110 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
23120 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
23130 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
23140 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
23150 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
23160 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
23170 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
23180 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
23190 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
231a0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
231b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
231c0 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
231d0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
231e0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
231f0 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36  ** [H16103] [H16
23200 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48  106] [H16109] [H
23210 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20  16112] [H16118] 
23220 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 34  [H16121] [H16124
23230 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48  ] [H16127].** [H
23240 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20  16130] [H16133] 
23250 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39  [H16136] [H16139
23260 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e  ] [H16142].*/.in
23270 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
23280 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
23290 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
232a0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
232b0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
232c0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
232d0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
232e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
232f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23300 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23310 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
23320 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
23330 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23340 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23350 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
23360 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
23370 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
23380 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23390 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
233a0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
233b0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
233c0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
233d0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
233e0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
233f0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
23400 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
23410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
23420 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
23430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23440 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23450 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
23460 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
23470 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
23480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
23490 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
234a0 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
234b0 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
234c0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
234d0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
234e0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
234f0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
23500 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
23510 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
23520 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
23530 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
23540 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
23550 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
23560 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
23570 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
23580 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
23590 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
235a0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
235b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
235c0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
235d0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
235e0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
235f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23600 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
23610 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
23620 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
23630 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
23640 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
23650 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
23660 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
23670 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
23680 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
23690 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
236a0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
236b0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
236c0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
236d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
236e0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
236f0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
23700 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
23710 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
23720 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
23730 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
23740 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
23750 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
23760 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
23770 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
23780 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
23790 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
237a0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
237b0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
237c0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
237d0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
237e0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
237f0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23800 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
23810 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
23820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
23830 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23840 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
23850 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
23860 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
23870 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
23880 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
23890 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
238a0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
238b0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
238c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
238d0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
238e0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
238f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
23900 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
23910 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
23920 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23930 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
23940 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
23950 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
23960 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
23970 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
23980 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
23990 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
239a0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
239b0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
239c0 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32  s {H15100} <S202
239d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00>.**.** The C-
239e0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
239f0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
23a00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
23a10 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
23a20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
23a30 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
23a40 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
23a50 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
23a60 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
23a70 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
23a80 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
23a90 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
23aa0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
23ab0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
23ac0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
23ad0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
23ae0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
23af0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
23b00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
23b10 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
23b20 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
23b30 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
23b40 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
23b50 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
23b60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
23b70 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
23b80 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
23b90 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
23ba0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23bb0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
23bc0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
23bd0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23be0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
23bf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
23c00 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
23c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
23c20 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
23c30 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
23c40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
23c50 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
23c60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23c70 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
23c80 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
23c90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23ca0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
23cb0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
23cc0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
23cd0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
23ce0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
23cf0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
23d00 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
23d10 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
23d20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
23d30 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
23d40 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
23d50 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
23d60 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
23d70 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
23d80 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
23d90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
23da0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23db0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
23dc0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
23dd0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
23de0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
23df0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
23e00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23e10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
23e20 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
23e30 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
23e40 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
23e50 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
23e60 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
23e70 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
23e80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
23e90 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
23ea0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
23eb0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
23ec0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
23ed0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
23ee0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
23ef0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
23f00 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vely..**.** The 
23f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
23f20 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
23f30 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
23f40 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
23f50 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
23f60 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
23f70 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
23f80 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
23f90 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
23fa0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
23fb0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
23fc0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
23fd0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
23fe0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
23ff0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
24000 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
24010 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
24020 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
24030 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
24040 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
24050 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
24060 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
24070 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
24080 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
24090 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
240a0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
240b0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
240c0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
240d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
240e0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
240f0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
24100 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
24110 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
24120 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
24130 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
24140 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
24150 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
24160 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24170 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
24180 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
24190 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
241a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
241b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
241c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
241d0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
241e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
241f0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
24200 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
24210 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
24220 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
24230 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
24240 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
24250 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
24260 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
24270 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
24280 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
24290 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
242a0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30  ments:.** [H1510
242b0 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35  3] [H15106] [H15
242c0 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48  109] [H15112] [H
242d0 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20  15115] [H15118] 
242e0 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34  [H15121] [H15124
242f0 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48  ].** [H15127] [H
24300 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20  15130] [H15133] 
24310 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73  [H15136].*/.cons
24320 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24330 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
24340 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
24350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
24360 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
24370 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24380 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
24390 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
243a0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
243b0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
243c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
243d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
243e0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
243f0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
24400 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
24410 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
24420 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
24430 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
24440 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
24450 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
24470 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24480 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24490 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
244a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
244b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
244c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
244d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
244e0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
244f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
24500 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
24510 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24520 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
24530 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
24540 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24560 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
24570 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
24580 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
24590 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
245a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
245b0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
245c0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
245d0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
245e0 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
245f0 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
24600 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
24610 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
24620 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
24630 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
24640 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
24650 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
24660 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
24670 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
24680 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
24690 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
246a0 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
246b0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
246c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
246d0 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
246e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
246f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
24700 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
24710 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
24720 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
24730 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
24740 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
24750 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
24760 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
24770 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
24780 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
24790 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
247a0 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
247b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
247c0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
247d0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
247e0 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
247f0 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
24800 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
24810 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
24820 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
24830 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
24840 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
24850 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
24860 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
24870 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
24880 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
24890 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
248a0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
248b0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
248c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
248d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
248e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
248f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
24900 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
24910 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
24920 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
24930 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
24940 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
24950 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31  11] [H16213] [H1
24960 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a  6215] [H16217].*
24970 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
24980 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
24990 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
249a0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
249b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
249c0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
249d0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34  Functions {H1624
249e0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
249f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
24a00 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
24a10 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
24a20 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
24a30 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
24a40 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
24a50 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
24a60 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
24a70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
24a80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
24a90 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
24aa0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
24ab0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
24ac0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
24ad0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
24ae0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
24af0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
24b00 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
24b10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
24b20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
24b30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
24b40 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
24b50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
24b60 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
24b70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
24b80 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
24b90 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  43].*/.void *sql
24ba0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
24bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
24bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24bd0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
24be0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
24bf0 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
24c00 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
24c10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24c20 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
24c30 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
24c40 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
24c50 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
24c60 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
24c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
24c80 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
24c90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
24ca0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24cb0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
24cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24cd0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
24ce0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
24cf0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
24d00 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
24d10 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
24d20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ion..**.** Requi
24d30 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
24d40 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  253].*/.sqlite3 
24d50 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
24d60 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
24d70 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
24d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
24d90 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
24da0 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20  y Data {H16270} 
24db0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
24dc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
24dd0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
24de0 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
24df0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
24e00 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
24e10 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
24e20 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
24e30 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
24e40 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
24e50 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
24e60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
24e70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
24e80 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
24e90 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
24ea0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
24eb0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
24ec0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
24ed0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
24ee0 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
24ef0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
24f00 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
24f10 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
24f20 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
24f30 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
24f40 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
24f50 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
24f60 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
24f70 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
24f80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
24f90 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
24fa0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
24fb0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
24fc0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
24fd0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
24fe0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
24ff0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
25000 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
25010 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
25020 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
25030 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
25040 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
25050 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
25060 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
25070 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
25080 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
25090 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
250a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
250b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
250c0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
250d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
250e0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
250f0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
25100 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
25110 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
25120 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
25130 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25140 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74  ction. If no met
25150 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
25160 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
25170 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
25180 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
25190 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
251a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
251b0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
251c0 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
251d0 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
251e0 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
251f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
25200 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
25210 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
25220 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
25230 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
25240 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
25250 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
25260 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
25270 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
25280 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
25290 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
252a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
252b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
252c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
252d0 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
252e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
252f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
25300 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
25310 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
25320 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
25330 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74  troyed..** If it
25340 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
25350 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
25360 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
25370 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
25380 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
25390 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
253a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
253b0 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
253c0 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
253d0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
253e0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
253f0 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
25400 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
25410 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
25420 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
25430 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
25440 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
25450 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
25460 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
25470 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
25480 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
25490 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
254a0 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
254b0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
254c0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
254d0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
254e0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
254f0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
25500 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
25510 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
25520 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
25530 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
25540 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
25550 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
25560 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
25570 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
25580 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
25590 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
255a0 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
255b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
255c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
255d0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
255e0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
255f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
25600 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
25610 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
25620 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32  * [H16272] [H162
25630 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31  74] [H16276] [H1
25640 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b  6277] [H16278] [
25650 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20  H16279].*/.void 
25660 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
25670 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
25680 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
25690 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
256a0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
256b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
256c0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
256d0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
256e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
256f0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
25700 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
25710 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
25720 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  80} <S30100>.**.
25730 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
25740 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
25750 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
25760 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
25770 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
25780 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
25790 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
257a0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
257b0 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
257c0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
257d0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
257e0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
257f0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
25800 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
25810 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
25820 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
25830 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
25840 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
25850 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
25860 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
25870 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
25880 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
25890 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
258a0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
258b0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
258c0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
258d0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
258e0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
258f0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
25900 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
25910 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
25920 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
25930 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
25940 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
25950 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
25960 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
25970 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
25980 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
25990 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
259a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
259b0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
259c0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
259d0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
259e0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
259f0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
25a00 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
25a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25a20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
25a30 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
25a40 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
25a50 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
25a60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
25a70 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
25a80 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
25a90 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
25aa0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
25ab0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
25ac0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
25ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25ae0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
25af0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25b00 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
25b10 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
25b20 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25b30 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
25b40 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
25b50 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
25b60 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
25b70 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
25b80 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
25b90 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
25ba0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
25bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25bc0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
25bd0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
25be0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
25bf0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
25c00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
25c10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25c20 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
25c30 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
25c40 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
25c50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
25c60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
25c70 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
25c80 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
25c90 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
25ca0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
25cb0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
25cc0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
25cd0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
25ce0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
25cf0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
25d00 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
25d10 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
25d20 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
25d30 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
25d40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25d50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
25d60 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
25d70 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
25d80 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
25d90 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
25da0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
25db0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
25dc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25dd0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
25de0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
25df0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
25e00 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
25e10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25e20 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
25e30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
25e40 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
25e50 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
25e60 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
25e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
25e80 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
25e90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
25ea0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
25eb0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
25ec0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
25ed0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
25ee0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
25ef0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
25f00 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
25f10 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
25f20 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
25f30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
25f40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
25f50 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
25f60 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
25f70 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
25f80 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
25f90 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
25fa0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25fb0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
25fc0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
25fd0 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
25fe0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
25ff0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
26000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26010 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
26020 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
26030 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
26040 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
26050 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
26060 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
26070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26080 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
26090 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
260a0 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
260b0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
260c0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
260d0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
260e0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
260f0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
26100 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26110 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
26120 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
26130 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
26140 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
26150 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
26160 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
26170 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
26180 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
26190 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
261a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
261b0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
261c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
261d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
261e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
261f0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
26200 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
26210 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
26220 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
26230 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
26240 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
26250 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
26260 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
26270 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
26280 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
26290 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
262a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
262b0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
262c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
262d0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
262e0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
262f0 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
26300 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
26310 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
26320 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
26330 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
26340 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
26350 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
26360 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
26370 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
26380 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
26390 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
263a0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
263b0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
263c0 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
263d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
263e0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
263f0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
26400 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
26410 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
26420 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
26430 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
26440 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
26450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26460 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
26470 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
26480 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
26490 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
264a0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
264b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
264c0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
264d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
264e0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
264f0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
26500 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
26510 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26520 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26530 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
26540 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
26550 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
26560 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
26570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26580 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
26590 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
265a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
265b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
265c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
265d0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
265e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
265f0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
26600 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
26610 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
26620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26630 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
26640 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
26650 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
26660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26670 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26680 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
26690 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
266a0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
266b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
266c0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
266d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
266e0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
266f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
26700 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
26710 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
26720 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
26730 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26740 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
26750 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
26760 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
26770 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
26780 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
26790 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
267a0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
267b0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
267c0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
267d0 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
267e0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
267f0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
26800 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
26810 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
26820 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
26830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26840 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
26850 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
26860 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
26870 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26880 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
26890 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
268a0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
268b0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
268c0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
268d0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
268e0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
268f0 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
26900 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
26910 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
26920 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
26930 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
26940 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
26950 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
26960 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
26970 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
26980 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
26990 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
269a0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
269b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
269c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
269d0 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
269e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
269f0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
26a00 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
26a10 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
26a20 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
26a30 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
26a40 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
26a50 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
26a60 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
26a70 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
26a80 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
26a90 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
26aa0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
26ab0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
26ac0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
26ad0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26af0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
26b00 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
26b10 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
26b20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
26b30 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
26b40 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
26b50 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
26b60 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
26b70 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
26b80 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
26b90 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
26ba0 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64  e it or call a d
26bb0 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69  estructor when i
26bc0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
26bd0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
26be0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
26bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26c00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26c10 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
26c20 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
26c30 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
26c40 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
26c50 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
26c60 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
26c70 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
26c80 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
26c90 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
26ca0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
26cb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
26cc0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
26cd0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
26ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
26cf0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
26d00 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
26d10 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
26d20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26d30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
26d40 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
26d50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
26d70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
26d80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
26d90 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
26da0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
26db0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
26dc0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
26dd0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
26de0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
26df0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
26e00 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
26e10 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
26e20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
26e30 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
26e40 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26e50 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
26e60 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
26e70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26e80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
26e90 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
26ea0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
26eb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26ec0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26ed0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
26ee0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
26ef0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
26f00 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
26f10 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
26f20 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
26f30 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
26f40 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
26f50 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
26f60 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
26f70 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
26f80 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
26f90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26fa0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
26fb0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
26fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
26fd0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
26fe0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
26ff0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
27000 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
27010 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48  403] [H16406] [H
27020 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32 5d 20  16409] [H16412] 
27030 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34 31 38  [H16415] [H16418
27040 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31 36 34  ] [H16421] [H164
27050 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20  24].** [H16427] 
27060 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34 33 33  [H16430] [H16433
27070 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31 36 34  ] [H16436] [H164
27080 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48 31  39] [H16442] [H1
27090 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a  6445] [H16448].*
270a0 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31 36 34  * [H16451] [H164
270b0 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48 31  54] [H16457] [H1
270c0 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a  6460] [H16463].*
270d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
270e0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
270f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
27100 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
27110 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
27120 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27130 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
27140 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
27150 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
27160 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
27170 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27180 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
27190 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
271a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
271b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
271c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
271d0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
271e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
271f0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
27200 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
27210 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27220 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
27230 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
27240 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27250 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
27260 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
27270 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
27280 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
27290 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
272a0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
272b0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
272c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
272d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
272e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
272f0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
27300 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
27310 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27320 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
27330 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
27340 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
27350 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
27360 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27370 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
27380 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
27390 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
273a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
273b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
273c0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
273d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
273e0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
273f0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27410 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
27420 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
27430 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
27440 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27460 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
27470 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
27480 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
27490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
274a0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
274b0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
274c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
274d0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
274e0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
274f0 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
27500 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
27510 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
27520 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
27530 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
27540 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
27550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27560 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
27570 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
27580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
27590 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
275a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
275b0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
275c0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
275d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
275e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
275f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
27600 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
27610 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
27620 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
27630 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27640 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
27650 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
27660 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
27670 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
27680 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
27690 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
276a0 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
276b0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
276c0 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
276d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
276e0 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16LE], or [SQLIT
276f0 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
27700 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
27710 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
27720 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
27730 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
27740 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
27750 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
27760 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
27770 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
27780 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
27790 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
277a0 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
277b0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
277c0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
277d0 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
277e0 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
277f0 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
27800 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
27810 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
27820 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
27830 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
27840 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
27850 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
27860 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
27870 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
27880 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
27890 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
278a0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
278b0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
278c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
278d0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
278e0 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
278f0 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
27900 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
27910 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
27920 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
27930 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
27940 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
27950 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
27960 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
27970 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
27980 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
27990 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
279a0 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
279b0 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
279c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
279d0 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
279e0 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
279f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
27a00 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
27a10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
27a20 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
27a30 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
27a40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
27a50 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
27a60 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
27a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
27a80 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
27a90 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
27aa0 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
27ab0 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
27ac0 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
27ad0 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
27ae0 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
27af0 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
27b00 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
27b10 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
27b20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
27b30 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
27b40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
27b50 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
27b60 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
27b70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
27b80 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
27b90 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
27ba0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
27bb0 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
27bc0 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
27bd0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
27be0 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
27bf0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
27c00 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
27c10 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
27c20 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
27c30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27c40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27c50 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
27c60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27c70 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
27c80 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
27c90 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
27ca0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
27cb0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
27cc0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
27cd0 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
27ce0 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
27cf0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
27d00 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
27d10 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
27d20 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
27d30 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
27d40 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
27d50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
27d60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27d70 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
27d80 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
27d90 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
27da0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
27db0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
27dc0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
27dd0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
27de0 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
27df0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27e00 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
27e10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
27e20 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
27e30 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
27e40 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
27e50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
27e60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
27e70 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  d16()]..**.** Re
27e80 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
27e90 48 31 36 36 30 33 5d 20 5b 48 31 36 36 30 34 5d  H16603] [H16604]
27ea0 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 36 36 30   [H16606] [H1660
27eb0 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 48 31 36  9] [H16612] [H16
27ec0 36 31 35 5d 20 5b 48 31 36 36 31 38 5d 20 5b 48  615] [H16618] [H
27ed0 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 36 36 32  16621].** [H1662
27ee0 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 48 31 36  4] [H16627] [H16
27ef0 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  630].*/.int sqli
27f00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27f10 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
27f20 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
27f30 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
27f40 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
27f50 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
27f60 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
27f70 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
27f80 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
27f90 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
27fa0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
27fb0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
27fc0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
27fd0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
27fe0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
27ff0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
28000 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
28010 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
28020 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
28030 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
28040 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
28050 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
28060 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
28070 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
28080 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
28090 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
280a0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
280b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
280c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
280d0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
280e0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
280f0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
28100 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
28110 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
28120 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
28130 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
28140 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
28150 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
28160 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
28170 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
28180 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
28190 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
281a0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
281b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
281c0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
281d0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
281e0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
281f0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
28200 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
28210 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
28220 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
28230 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
28240 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28250 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
28260 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
28270 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
28280 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
28290 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
282a0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
282b0 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
282c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
282d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
282e0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
282f0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
28300 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
28310 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
28320 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
28330 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
28340 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
28350 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
28360 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
28370 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
28380 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
28390 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
283a0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
283b0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
283c0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
283d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
283e0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
283f0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28400 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
28410 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
28420 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
28430 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
28440 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
28450 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
28460 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
28470 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
28480 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
28490 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
284a0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
284b0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
284c0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
284d0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
284e0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
284f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
28500 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
28510 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
28520 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
28530 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
28540 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
28550 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
28560 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
28570 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
28580 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28590 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
285a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
285b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
285c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
285d0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
285e0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
285f0 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 5d 20 5b  s:.** [H16702] [
28600 48 31 36 37 30 34 5d 20 5b 48 31 36 37 30 36 5d  H16704] [H16706]
28610 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28620 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
28630 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
28640 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
28650 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
28660 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
28670 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
28680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
28690 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
286a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
286b0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
286c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
286d0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
286e0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
286f0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
28700 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
28710 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
28720 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
28730 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
28740 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
28750 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
28760 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
28770 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
28780 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
28790 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
287a0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
287b0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
287c0 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
287d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
287e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
287f0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
28800 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
28810 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
28820 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
28830 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
28840 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
28850 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
28860 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
28870 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
28880 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
28890 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
288a0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
288b0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
288c0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
288d0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
288e0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
288f0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
28900 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
28910 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
28920 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
28930 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
28940 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
28950 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
28960 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28970 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28980 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
28990 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
289a0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
289b0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
289c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
289d0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
289e0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
289f0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48   A Short Time {H
28a00 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a  10530} <S40410>.
28a10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28a20 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
28a30 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
28a40 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
28a50 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
28a60 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
28a70 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
28a80 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
28a90 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
28aa0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
28ab0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
28ac0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
28ad0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
28ae0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
28af0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
28b00 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
28b10 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
28b20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
28b30 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
28b40 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
28b50 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
28b60 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
28b70 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
28b80 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
28b90 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
28ba0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rned..**.** SQLi
28bb0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
28bc0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
28bd0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
28be0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
28bf0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
28c00 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
28c10 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ct..**.** Requir
28c20 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 33 33 5d  ements: [H10533]
28c30 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74   [H10536].*/.int
28c40 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
28c50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28c60 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
28c70 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
28c80 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
28c90 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30   {H10310} <S2000
28ca0 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0>.**.** If this
28cb0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
28cc0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
28cd0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
28ce0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
28cf0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
28d00 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
28d10 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
28d20 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
28d30 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
28d40 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
28d50 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
28d60 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
28d70 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
28d80 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
28d90 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
28da0 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
28db0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
28dc0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
28dd0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
28de0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
28df0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
28e00 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
28e10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
28e20 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
28e30 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
28e40 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
28e50 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
28e60 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
28e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28e80 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
28e90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
28ea0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
28eb0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
28ec0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
28ed0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
28ee0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
28ef0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
28f00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
28f10 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
28f20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
28f30 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
28f40 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
28f50 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
28f60 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
28f70 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
28f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74  er..**.** The [t
28f90 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
28fa0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
28fb0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
28fc0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
28fd0 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
28fe0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
28ff0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
29000 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 68 65 72  alloc].  Further
29010 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
29020 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
29030 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
29040 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
29050 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
29060 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
29070 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
29080 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
29090 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
290a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
290b0 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
290c0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
290d0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
290e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
290f0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
29100 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
29110 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
29120 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
29130 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
29140 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
29150 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
29160 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
29170 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
29180 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
29190 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
291a0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
291b0 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
291c0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
291d0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
291e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
291f0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
29200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
29210 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
29220 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d  it Mode {H12930}
29230 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S60200>.** KEY
29240 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
29250 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  it mode}.**.** T
29260 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
29270 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
29280 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
29290 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
292a0 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
292b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
292c0 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
292d0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
292e0 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
292f0 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ely.  Autocommit
29300 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
29310 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63  efault..** Autoc
29320 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
29330 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
29340 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
29350 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
29360 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
29370 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
29380 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
29390 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
293a0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
293b0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
293c0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
293d0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
293e0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
293f0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
29400 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
29410 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
29420 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
29430 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
29440 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
29450 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
29460 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
29470 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
29480 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
29490 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
294a0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
294b0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
294c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
294d0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
294e0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
294f0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
29500 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
29510 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
29520 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
29530 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
29540 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
29550 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
29560 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
29570 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
29580 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
29590 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
295a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
295b0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
295c0 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33   [H12931] [H1293
295d0 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32  2] [H12933] [H12
295e0 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  934].*/.int sqli
295f0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
29600 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
29610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
29620 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
29630 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
29640 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
29650 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30  {H13120} <S60600
29660 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
29670 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
29680 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29690 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
296a0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
296b0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
296c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
296d0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68  nt] belongs.  Th
296e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
296f0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
29700 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
29710 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
29720 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
29730 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
29740 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
29750 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
29760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29770 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
29780 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
29790 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
297a0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
297b0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
297c0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  irst place..**.*
297d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
297e0 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69  [H13123].*/.sqli
297f0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
29800 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
29810 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29820 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
29830 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
29840 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30  tatement {H13140
29850 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60600>.**.**
29860 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
29870 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29880 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
29890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
298a0 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
298b0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
298c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
298d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
298e0 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
298f0 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
29900 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29910 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
29920 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
29930 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
29940 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
29950 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29960 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
29970 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
29980 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
29990 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
299a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
299b0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
299c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
299d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
299e0 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
299f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
29a00 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
29a10 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
29a20 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
29a30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
29a40 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
29a50 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
29a60 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
29a70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
29a80 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b  ents: [H13143] [
29a90 48 31 33 31 34 36 5d 20 5b 48 31 33 31 34 39 5d  H13146] [H13149]
29aa0 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c   [H13152].*/.sql
29ab0 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
29ac0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
29ad0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
29ae0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
29af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29b00 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
29b10 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
29b20 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
29b30 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2950} <S60400>.*
29b40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29b50 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
29b60 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
29b70 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
29b80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29b90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
29ba0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
29bb0 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
29bc0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
29bd0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
29be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
29bf0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
29c00 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
29c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29c20 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
29c30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
29c40 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
29c50 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
29c60 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
29c70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29c80 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
29c90 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
29ca0 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
29cb0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
29cc0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
29cd0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
29ce0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
29cf0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
29d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29d10 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
29d20 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
29d30 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
29d40 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
29d50 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68  llback..** If th
29d60 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
29d70 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
29d80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
29d90 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
29da0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
29db0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
29dc0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66  llback..**.** If
29dd0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
29de0 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
29df0 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
29e00 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69  .** pArg value i
29e10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
29e20 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
29e30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
29e40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
29e50 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
29e60 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
29e70 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
29e80 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
29e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
29ea0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
29eb0 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
29ec0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
29ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
29ee0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
29ef0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
29f00 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
29f10 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
29f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29f30 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
29f40 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
29f50 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
29f60 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
29f70 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
29f80 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
29f90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
29fa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29fb0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
29fc0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
29fd0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
29fe0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
29ff0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
2a000 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52  ragraph..**.** R
2a010 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
2a020 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
2a030 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
2a040 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
2a050 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
2a060 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
2a070 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
2a080 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
2a090 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
2a0a0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
2a0b0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
2a0c0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
2a0d0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
2a0e0 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
2a0f0 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
2a100 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
2a110 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2a120 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2a130 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2a140 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
2a150 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2a160 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
2a170 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a180 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
2a190 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
2a1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
2a1b0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
2a1c0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
2a1d0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2a1e0 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
2a1f0 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
2a200 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
2a210 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
2a220 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65  </todo>.**.** Re
2a230 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
2a240 48 31 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d  H12951] [H12952]
2a250 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35   [H12953] [H1295
2a260 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b  4] [H12955].** [
2a270 48 31 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d  H12961] [H12962]
2a280 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36   [H12963] [H1296
2a290 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  4].*/.void *sqli
2a2a0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2a2b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2a2c0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2a2d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2a2e0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2a2f0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2a300 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2a310 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a320 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2a330 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2a340 63 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36  cks {H12970} <S6
2a350 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
2a360 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2a370 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2a380 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2a390 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
2a3a0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2a3b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a3c0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
2a3d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a3e0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2a3f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
2a400 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
2a410 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
2a420 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
2a430 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2a440 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2a450 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2a460 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2a470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2a480 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2a490 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2a4a0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2a4b0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
2a4c0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
2a4d0 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
2a4e0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
2a4f0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
2a500 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2a510 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2a520 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
2a530 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2a540 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2a550 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2a560 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
2a570 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
2a580 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2a590 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
2a5a0 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
2a5b0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2a5c0 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
2a5d0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
2a5e0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
2a5f0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
2a600 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
2a610 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
2a620 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2a630 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
2a640 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
2a650 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
2a660 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
2a670 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
2a680 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68  ected row..** Th
2a690 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
2a6a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a6b0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
2a6c0 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20   row..** In the 
2a6d0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
2a6e0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
2a6f0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
2a700 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
2a710 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
2a720 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
2a730 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
2a740 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
2a750 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
2a760 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
2a770 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
2a780 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
2a790 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
2a7a0 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61   hook implementa
2a7b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
2a7c0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
2a7d0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
2a7e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a7f0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
2a800 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
2a810 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ok.  Any actions
2a820 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
2a830 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a840 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
2a850 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
2a860 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
2a870 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
2a880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2a890 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
2a8a0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2a8b0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
2a8c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a8d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2a8e0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
2a8f0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
2a900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a910 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
2a920 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
2a930 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2a940 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ph..**.** If ano
2a950 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
2a960 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
2a970 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
2a980 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65  g value.** is re
2a990 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
2a9a0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
2a9b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
2a9c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2a9d0 39 37 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48  971] [H12973] [H
2a9e0 31 32 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20  12975] [H12977] 
2a9f0 5b 48 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31  [H12979] [H12981
2aa00 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39  ] [H12983] [H129
2aa10 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  86].*/.void *sql
2aa20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2aa30 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2aa40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
2aa50 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
2aa60 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
2aa70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
2aa80 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
2aa90 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2aaa0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2aab0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20  red Pager Cache 
2aac0 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30  {H10330} <S30900
2aad0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2aae0 73 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73  shared cache} {s
2aaf0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
2ab00 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2ab10 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
2ab20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
2ab30 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
2ab40 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
2ab50 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
2ab60 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
2ab70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ab80 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
2ab90 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
2aba0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
2abb0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2abc0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
2abd0 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
2abe0 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
2abf0 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
2ac00 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73  e..**.** Cache s
2ac10 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
2ac20 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66  d and disabled f
2ac30 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f  or an entire pro
2ac40 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73  cess..** This is
2ac50 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
2ac60 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2ac70 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76  .5.0. In prior v
2ac80 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2ac90 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61  e,.** sharing wa
2aca0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
2acb0 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
2acc0 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
2acd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
2ace0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2acf0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2ad00 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2ad10 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2ad20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ad30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2ad40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2ad50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2ad60 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2ad70 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2ad80 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2ad90 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2ada0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2adb0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2adc0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2add0 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
2ade0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
2adf0 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
2ae00 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
2ae10 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  e.  When shared.
2ae20 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
2ae30 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
2ae40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
2ae50 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
2ae60 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
2ae70 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
2ae80 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
2ae90 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
2aea0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2aeb0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
2aec0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
2aed0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
2aee0 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
2aef0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
2af00 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2af10 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
2af20 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
2af30 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2af40 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
2af50 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
2af60 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
2af70 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2af80 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2af90 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
2afa0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
2afb0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
2afc0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
2afd0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
2afe0 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
2aff0 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a  -Cache Mode].**.
2b000 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2b010 20 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33   [H10331] [H1033
2b020 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30  6] [H10337] [H10
2b030 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  339].*/.int sqli
2b040 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2b050 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2b060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2b070 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2b080 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33  eap Memory {H173
2b090 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a  40} <S30220>.**.
2b0a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2b0b0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2b0c0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2b0d0 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
2b0e0 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
2b0f0 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
2b100 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
2b110 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2b120 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
2b130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
2b140 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65  brary. {END}  Me
2b150 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
2b160 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
2b170 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
2b180 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
2b190 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
2b1a0 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
2b1b0 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  y..** sqlite3_re
2b1c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
2b1d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b1e0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
2b1f0 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
2b200 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
2b210 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
2b220 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
2b230 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ted..**.** Requi
2b240 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31  rements: [H17341
2b250 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e  ] [H17342].*/.in
2b260 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
2b270 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
2b280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b290 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
2b2a0 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37  n Heap Size {H17
2b2b0 33 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a  350} <S30220>.**
2b2c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b2d0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2b2e0 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63  ) interface plac
2b2f0 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  es a "soft" limi
2b300 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75  t.** on the amou
2b310 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
2b320 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
2b330 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
2b340 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  e..** If an inte
2b350 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
2b360 69 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61  is requested tha
2b370 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
2b380 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20  he.** soft heap 
2b390 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
2b3a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2b3b0 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  ] is invoked one
2b3c0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65   or.** more time
2b3d0 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
2b3e0 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
2b3f0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  he allocation is
2b400 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
2b410 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63  * The limit is c
2b420 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
2b430 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65  cause if [sqlite
2b440 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2b450 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72  ()].** cannot fr
2b460 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
2b470 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
2b480 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
2b490 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
2b4a0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
2b4b0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
2b4c0 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
2b4d0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
2b4e0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  eds..**.** A neg
2b4f0 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
2b500 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
2b510 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
2b520 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2b530 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2b540 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2b550 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
2b560 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
2b570 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
2b580 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
2b590 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
2b5a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2b5b0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
2b5c0 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
2b5d0 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
2b5e0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2b5f0 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20  imit..** But if 
2b600 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2b610 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f  mit cannot be ho
2b620 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e  nored, execution
2b630 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
2b640 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
2b650 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
2b660 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
2b670 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61  e limit is.** ca
2b680 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
2b690 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
2b6a0 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
2b6b0 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
2b6c0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2b6d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
2b6e0 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
2b6f0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2b700 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
2b710 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
2b720 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2b730 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
2b740 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
2b750 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
2b760 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2b770 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2b780 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
2b790 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
2b7a0 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
2b7b0 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
2b7c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
2b7d0 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
2b7e0 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
2b7f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2b800 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
2b810 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
2b820 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
2b830 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
2b840 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
2b850 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
2b860 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
2b870 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ds..**.** Requir
2b880 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33  ements:.** [H163
2b890 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31  51] [H16352] [H1
2b8a0 36 33 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b  6353] [H16354] [
2b8b0 48 31 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d  H16355] [H16358]
2b8c0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2b8d0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2b8e0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2b8f0 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2b900 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2b910 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2b920 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30  le {H12850} <S60
2b930 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
2b940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b950 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2b960 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2b970 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2b980 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2b990 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2b9a0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2b9b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2b9c0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2b9d0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2b9e0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2b9f0 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
2ba00 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2ba10 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2ba20 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2ba30 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2ba40 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
2ba50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ba60 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
2ba70 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2ba80 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
2ba90 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
2baa0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2bab0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2bac0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2bad0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2bae0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2baf0 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
2bb00 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
2bb10 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
2bb20 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
2bb30 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
2bb40 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61  m used by the da
2bb50 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f  tabase engine to
2bb60 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
2bb70 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
2bb80 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
2bb90 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2bba0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2bbb0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2bbc0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2bbd0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2bbe0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2bbf0 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2bc00 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2bc10 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2bc20 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2bc30 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74  L..**.** Metadat
2bc40 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
2bc50 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
2bc60 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
2bc70 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
2bc80 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
2bc90 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
2bca0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2bcb0 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61  . Any of these a
2bcc0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
2bcd0 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
2bce0 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
2bcf0 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
2bd00 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
2bd10 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  omitted..**.** <
2bd20 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2bd30 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2bd40 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
2bd50 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
2bd60 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
2bd70 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
2bd80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
2bd90 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
2bda0 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
2bdb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
2bdc0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
2bdd0 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
2bde0 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
2bdf0 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72   sequence.** <tr
2be00 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69  ><td> 7th <td> i
2be10 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
2be20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68  True if column h
2be30 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
2be40 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e  nstraint.** <tr>
2be50 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e  <td> 8th <td> in
2be60 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2be70 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2be80 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
2be90 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e  MARY KEY.** <tr>
2bea0 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e  <td> 9th <td> in
2beb0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2bec0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2bed0 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d   [AUTOINCREMENT]
2bee0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2bef0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2bf00 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
2bf10 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2bf20 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
2bf30 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
2bf40 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
2bf50 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
2bf60 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2bf70 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
2bf80 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
2bf90 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
2bfa0 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
2bfb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
2bfc0 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
2bfd0 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
2bfe0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2bff0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2c000 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
2c010 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
2c020 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
2c030 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
2c040 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
2c050 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2c060 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
2c070 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
2c080 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2c090 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2c0a0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
2c0b0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2c0c0 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
2c0d0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2c0e0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2c0f0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2c100 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2c110 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2c120 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2c130 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2c140 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2c150 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2c160 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2c170 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c180 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2c190 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2c1a0 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2c1b0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2c1c0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2c1d0 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
2c1e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
2c1f0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
2c200 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
2c210 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
2c220 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
2c230 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
2c240 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
2c250 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
2c260 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
2c270 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
2c280 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2c290 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
2c2a0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
2c2b0 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68  ge left.** in th
2c2c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2c2d0 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72  ection] (to be r
2c2e0 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
2c2f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
2c300 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
2c310 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
2c320 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2c330 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2c340 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2c350 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2c360 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2c370 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2c380 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
2c390 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
2c3a0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
2c3b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c3d0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
2c3e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c3f0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
2c400 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c410 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
2c420 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
2c430 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
2c440 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
2c450 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
2c460 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
2c470 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
2c480 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2c490 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
2c4a0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
2c4b0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
2c4c0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
2c4d0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
2c4e0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
2c4f0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
2c500 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
2c510 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
2c520 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2c530 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
2c540 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
2c550 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
2c560 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
2c570 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2c580 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
2c590 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
2c5a0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
2c5b0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2c5c0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
2c5d0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
2c5e0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2c5f0 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
2c600 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30  Extension {H1260
2c610 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a  0} <S20500>.**.*
2c620 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2c630 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
2c640 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2c650 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
2c660 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  d file..**.** {H
2c670 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74  12601} The sqlit
2c680 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2c690 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
2c6a0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
2c6b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
2c6c0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2c6d0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
2c6e0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
2c6f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  le..**.** {H1260
2c700 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  2} The entry poi
2c710 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a  nt is zProc..**.
2c720 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f  ** {H12603} zPro
2c730 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
2c740 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
2c750 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
2c760 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  point.**        
2c770 20 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73    defaults to "s
2c780 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
2c790 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _init"..**.** {H
2c7a0 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74  12604} The sqlit
2c7b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2c7c0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68  n() interface sh
2c7d0 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  all return.**   
2c7e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
2c7f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
2c800 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2c810 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
2c820 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20  es wrong..**.** 
2c830 7b 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65  {H12605} If an e
2c840 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
2c850 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
2c860 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  0, then the.**  
2c870 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2c880 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2c890 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2c8a0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
2c8b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a            fill *
2c8c0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2c8d0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2c8e0 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2c8f0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  y.**          ob
2c900 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2c910 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
2c920 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69  {END}  The calli
2c930 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  ng function.**  
2c940 20 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66          should f
2c950 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20  ree this memory 
2c960 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2c970 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2c980 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65  ** {H12606} Exte
2c990 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
2c9a0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
2c9b0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2c9c0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
2c9d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2c9e0 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ] prior to calli
2c9f0 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20  ng this API,.** 
2ca00 20 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69           otherwi
2ca10 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
2ca20 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
2ca30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
2ca40 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
2ca50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ca60 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
2ca70 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
2ca80 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
2ca90 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
2caa0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
2cab0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
2cac0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
2cad0 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
2cae0 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
2caf0 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
2cb00 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
2cb10 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
2cb20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
2cb30 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
2cb40 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
2cb50 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
2cb60 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
2cb70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cb80 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
2cb90 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
2cba0 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32  ing {H12620} <S2
2cbb0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  0500>.**.** So a
2cbc0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2cbd0 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2cbe0 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2cbf0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2cc00 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
2cc10 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
2cc20 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
2cc30 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
2cc40 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
2cc50 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
2cc60 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
2cc70 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
2cc80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
2cc90 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
2cca0 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
2ccb0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2ccc0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
2ccd0 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
2cce0 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * Extension load
2ccf0 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65  ing is off by de
2cd00 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65  fault. See ticke
2cd10 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b  t #1863..**.** {
2cd20 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65  H12621} Call the
2cd30 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2cd40 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2cd50 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e   routine with on
2cd60 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20  off==1.**       
2cd70 20 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e     to turn exten
2cd80 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
2cd90 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
2cda0 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
2cdb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
2cdc0 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
2cdd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20  .**.** {H12622} 
2cde0 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2cdf0 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
2ce00 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ult..*/.int sqli
2ce10 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2ce20 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
2ce30 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
2ce40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce50 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
2ce60 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
2ce70 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53  ions {H12640} <S
2ce80 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2ce90 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
2cea0 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
2ceb0 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
2cec0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
2ced0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
2cee0 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
2cef0 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
2cf00 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
2cf10 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64  ** to all new [d
2cf20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cf30 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ons]. {END}.**.*
2cf40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
2cf50 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
2cf60 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
2cf70 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61   in an array tha
2cf80 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  t is.** obtained
2cf90 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2cfa0 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f  alloc()].  If yo
2cfb0 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c  u run a memory l
2cfc0 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f  eak checker.** o
2cfd0 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61  n your program a
2cfe0 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20  nd it reports a 
2cff0 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20  leak because of 
2d000 74 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f  this array, invo
2d010 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ke.** [sqlite3_r
2d020 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2d030 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20  ion()] prior to 
2d040 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
2d050 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
2d060 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73  ** {H12641} This
2d070 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
2d080 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
2d090 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
2d0a0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
2d0b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2d0c0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2d0d0 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  a new [database 
2d0e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20  connection].**  
2d0f0 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65          is opene
2d100 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2d110 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2d120 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
2d130 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2d140 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2d150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d  ..**.** {H12642}
2d160 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
2d170 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
2d180 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
2d190 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20  is routine.**   
2d1a0 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20         multiple 
2d1b0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2d1c0 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
2d1d0 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a   harmless..**.**
2d1e0 20 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72   {H12643} This r
2d1f0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
2d200 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
2d210 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
2d220 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rray.**         
2d230 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65   that is obtaine
2d240 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d250 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
2d260 20 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61   {H12644} Automa
2d270 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
2d280 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
2d290 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20  threads..*/.int 
2d2a0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
2d2b0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
2d2c0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
2d2d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d2e0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
2d2f0 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
2d300 61 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c  ading {H12660} <
2d310 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20500>.**.** Th
2d320 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
2d330 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
2d340 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61  sly registered a
2d350 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65  utomatic.** exte
2d360 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49  nsions. {END}  I
2d370 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  t undoes the eff
2d380 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
2d390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  .** [sqlite3_aut
2d3a0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63  o_extension()] c
2d3b0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  alls..**.** {H12
2d3c0 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  661} This functi
2d3d0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20  on disables all 
2d3e0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
2d3f0 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
2d400 20 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65    automatic exte
2d410 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nsions..**.** {H
2d420 31 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63  12662} This func
2d430 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75  tion disables au
2d440 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2d450 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
2d460 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
2d470 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
2d480 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
2d490 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  /*.****** EXPERI
2d4a0 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
2d4b0 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
2d4c0 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
2d4d0 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
2d4e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
2d4f0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
2d500 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
2d510 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
2d520 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
2d530 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
2d540 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
2d550 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
2d560 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
2d570 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
2d580 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
2d590 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
2d5a0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
2d5b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
2d5c0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
2d5d0 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
2d5e0 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
2d5f0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
2d600 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
2d610 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
2d620 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
2d630 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
2d640 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
2d650 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
2d660 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2d670 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
2d680 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2d690 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
2d6a0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
2d6b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
2d6c0 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
2d6d0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
2d6e0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2d6f0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2d700 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2d710 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
2d720 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
2d730 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
2d740 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
2d750 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
2d760 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30  le Object {H1800
2d770 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
2d780 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2d790 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
2d7a0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
2d7b0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2d7c0 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
2d7d0 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
2d7e0 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
2d7f0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
2d800 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
2d810 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d820 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
2d830 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
2d840 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
2d850 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
2d860 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2d870 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76  odule..**.** A v
2d880 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2d890 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
2d8a0 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
2d8b0 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
2d8c0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
2d8d0 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
2d8e0 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
2d8f0 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
2d900 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2d910 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
2d920 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2d930 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
2d940 2a 2a 20 54 68 65 20 72 65 67 69 73 74 72 61 74  ** The registrat
2d950 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
2d960 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
2d970 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
2d980 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
2d990 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
2d9a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d9b0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
2d9c0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
2d9d0 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
2d9e0 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
2d9f0 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
2da00 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
2da10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2da20 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
2da30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
2da40 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
2da50 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
2da60 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
2da70 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
2da80 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2da90 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
2daa0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
2dab0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
2dac0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
2dad0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
2dae0 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
2daf0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
2db00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2db10 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
2db20 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
2db30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
2db40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
2db50 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
2db60 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
2db70 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
2db80 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
2db90 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
2dba0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
2dbb0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
2dbc0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2dbd0 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
2dbe0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2dbf0 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
2dc00 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2dc10 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
2dc20 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
2dc30 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
2dc40 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
2dc50 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
2dc60 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
2dc70 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2dc80 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
2dc90 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
2dca0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
2dcb0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
2dcc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
2dcd0 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
2dce0 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
2dcf0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2dd00 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
2dd10 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
2dd20 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
2dd30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2dd40 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
2dd50 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
2dd60 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
2dd70 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2dd80 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
2dd90 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
2dda0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
2ddb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
2ddc0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
2ddd0 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
2dde0 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
2ddf0 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
2de00 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2de10 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
2de20 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2de30 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
2de40 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
2de50 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2de60 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
2de70 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2de80 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
2de90 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
2dea0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
2deb0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
2dec0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
2ded0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dee0 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
2def0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2df00 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2df10 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
2df20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2df30 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
2df40 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
2df50 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2df60 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
2df70 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
2df80 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
2df90 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
2dfa0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b  ng Information {
2dfb0 48 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18100} <S20400>
2dfc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
2dfd0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2dfe0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2dff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e000 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
2e010 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
2e020 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
2e030 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
2e040 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
2e050 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
2e060 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
2e070 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
2e080 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
2e090 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2e0a0 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
2e0b0 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
2e0c0 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
2e0d0 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
2e0e0 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
2e0f0 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
2e100 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
2e110 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
2e120 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
2e130 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  lds..**.** The a
2e140 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
2e150 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
2e160 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2e170 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
2e180 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
2e190 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
2e1a0 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
2e1b0 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
2e1c0 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
2e1d0 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c  =.  The particul
2e1e0 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
2e1f0 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
2e200 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
2e210 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e220 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
2e230 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
2e240 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61  nt[].iColumn.  a
2e250 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
2e260 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
2e270 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
2e280 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
2e290 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
2e2a0 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
2e2b0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
2e2c0 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
2e2d0 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
2e2e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69  ..**.** The opti
2e2f0 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
2e300 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
2e310 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
2e320 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
2e330 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
2e340 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
2e350 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
2e360 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
2e370 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
2e380 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
2e390 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
2e3a0 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
2e3b0 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
2e3c0 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
2e3d0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
2e3e0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
2e3f0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
2e400 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
2e410 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
2e420 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
2e430 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
2e440 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
2e450 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  * Information ab
2e460 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
2e470 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
2e480 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
2e490 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66  .** Each term of
2e4a0 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
2e4b0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
2e4c0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2e4d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
2e4e0 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
2e4f0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
2e500 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
2e510 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
2e520 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
2e530 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
2e540 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
2e550 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
2e560 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
2e570 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
2e580 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
2e590 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
2e5a0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
2e5b0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
2e5c0 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
2e5d0 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
2e5e0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
2e5f0 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
2e600 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
2e610 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
2e620 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
2e630 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
2e640 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
2e650 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
2e660 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
2e670 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
2e680 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
2e690 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
2e6a0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
2e6b0 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
2e6c0 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  ethod..** [sqlit
2e6d0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73  e3_free()] is us
2e6e0 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
2e6f0 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  r if and only if
2e700 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
2e710 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
2e720 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
2e730 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
2e740 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
2e750 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74  [xFilter]/[xNext
2e760 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a  ] will occur in.
2e770 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f  ** the correct o
2e780 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20  rder to satisfy 
2e790 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
2e7a0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73  use so that no s
2e7b0 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69  eparate.** sorti
2e7c0 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69  ng step is requi
2e7d0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  red..**.** The e
2e7e0 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
2e7f0 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
2e800 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
2e810 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
2e820 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
2e830 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
2e840 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
2e850 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
2e860 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
2e870 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
2e880 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
2e890 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
2e8a0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
2e8b0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
2e8c0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
2e8d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2e8e0 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
2e8f0 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
2e900 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
2e910 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
2e920 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
2e930 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
2e940 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
2e950 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
2e960 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
2e970 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
2e980 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
2e990 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2e9a0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
2e9b0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
2e9c0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
2e9d0 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
2e9e0 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
2e9f0 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
2ea00 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
2ea10 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
2ea20 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
2ea30 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
2ea40 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
2ea50 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
2ea60 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
2ea70 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
2ea80 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
2ea90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
2eaa0 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
2eab0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
2eac0 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
2ead0 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
2eae0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
2eaf0 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
2eb00 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
2eb10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2eb20 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
2eb30 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
2eb40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2eb50 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
2eb60 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
2eb70 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
2eb80 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
2eb90 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
2eba0 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
2ebb0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
2ebc0 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
2ebd0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
2ebe0 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
2ebf0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2ec00 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
2ec10 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
2ec20 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
2ec30 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
2ec40 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
2ec50 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
2ec60 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
2ec70 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
2ec80 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
2ec90 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
2eca0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
2ecb0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
2ecc0 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
2ecd0 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
2ece0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
2ecf0 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
2ed00 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
2ed10 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
2ed20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
2ed30 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
2ed40 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
2ed50 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
2ed60 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
2ed70 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
2ed80 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
2ed90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
2eda0 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
2edb0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
2edc0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
2edd0 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
2ede0 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
2edf0 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
2ee00 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
2ee10 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
2ee20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
2ee30 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
2ee40 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
2ee50 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
2ee60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2ee70 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
2ee80 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
2ee90 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
2eea0 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
2eeb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2eec0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
2eed0 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
2eee0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
2eef0 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
2ef00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ef10 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
2ef20 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
2ef30 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
2ef40 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
2ef50 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
2ef60 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30  on {H18200} <S20
2ef70 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  400>.** EXPERIME
2ef80 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
2ef90 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
2efa0 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
2efb0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
2efc0 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
2efd0 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d  * Module names m
2efe0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
2eff0 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
2f000 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
2f010 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
2f020 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
2f030 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
2f040 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
2f050 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
2f060 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
2f070 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e  .** The module n
2f080 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ame is registere
2f090 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  d on the [databa
2f0a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
2f0b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
2f0c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f0d0 65 72 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66  er.  The name of
2f0e0 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
2f0f0 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
2f100 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2f110 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
2f120 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
2f130 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
2f140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f150 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
2f160 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68  le module].   Th
2f170 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61  e fourth.** para
2f180 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
2f190 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74  trary client dat
2f1a0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
2f1b0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2f1c0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43  .** into the [xC
2f1d0 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
2f1e0 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
2f1f0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
2f200 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65  le module.** whe
2f210 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20  n a new virtual 
2f220 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e  table is be bein
2f230 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69  g created or rei
2f240 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a  nitialized..**.*
2f250 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2f260 20 68 61 73 20 65 78 61 63 74 6c 79 20 74 68 65   has exactly the
2f270 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
2f280 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  calling.** [sqli
2f290 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2f2a0 65 5f 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e  e_v2()] with a N
2f2b0 55 4c 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ULL client data 
2f2c0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53  destructor..*/.S
2f2d0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
2f2e0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
2f2f0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20  reate_module(.  
2f300 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2f310 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
2f320 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
2f330 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
2f340 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
2f350 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2f360 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
2f370 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
2f380 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
2f390 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
2f3a0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
2f3b0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
2f3c0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20  d *pClientData  
2f3d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
2f3e0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
2f3f0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29  te/xConnect */.)
2f400 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f410 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
2f420 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
2f430 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32  ementation {H182
2f440 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  10} <S20400>.** 
2f450 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2f460 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2f470 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
2f480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2f490 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65  ate_module()] me
2f4a0 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20  thod,.** except 
2f4b0 74 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65  that it has an e
2f4c0 78 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74  xtra parameter t
2f4d0 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20  o specify .** a 
2f4e0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
2f4f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65  ion for the clie
2f500 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  nt data pointer.
2f510 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
2f520 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2f530 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2f540 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  (if it is not NU
2f550 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a  LL) when SQLite.
2f560 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  ** no longer nee
2f570 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  ds the pClientDa
2f580 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f  ta pointer.  .*/
2f590 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
2f5a0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
2f5b0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
2f5c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2f5d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2f5e0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
2f5f0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
2f600 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
2f610 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2f620 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
2f630 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
2f640 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
2f650 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
2f660 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
2f670 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
2f680 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
2f690 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ata,         /* 
2f6a0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
2f6b0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
2f6c0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
2f6d0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
2f6e0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
2f6f0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
2f700 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2f710 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
2f720 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a  ble Instance Obj
2f730 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32  ect {H18010} <S2
2f740 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2f750 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
2f760 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2f770 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
2f780 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2f790 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
2f7a0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
2f7b0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c  s.** of the foll
2f7c0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
2f7d0 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
2f7e0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
2f7f0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  e.** of the [vir
2f800 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61  tual table].  Ea
2f810 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
2f820 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
2f830 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
2f840 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
2f850 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
2f860 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
2f870 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
2f880 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
2f890 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
2f8a0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
2f8b0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
2f8c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2f8d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
2f8e0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
2f8f0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
2f900 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
2f910 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
2f920 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
2f930 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
2f940 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
2f950 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
2f960 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
2f970 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
2f980 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
2f990 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
2f9a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
2f9b0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
2f9c0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
2f9d0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
2f9e0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
2f9f0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
2fa00 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
2fa10 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
2fa20 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
2fa30 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2fa40 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
2fa50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2fa60 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
2fa70 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
2fa80 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
2fa90 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
2faa0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
2fab0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
2fac0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
2fad0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
2fae0 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
2faf0 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
2fb00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73             /* Us
2fb10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f  ed internally */
2fb20 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  .  char *zErrMsg
2fb30 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2fb40 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73     /* Error mess
2fb50 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  age from sqlite3
2fb60 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20  _mprintf() */.  
2fb70 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
2fb80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2fb90 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
2fba0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
2fbb0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
2fbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
2fbd0 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f  tual Table Curso
2fbe0 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32  r Object  {H1802
2fbf0 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
2fc00 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2fc10 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69  _vtab_cursor {vi
2fc20 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73  rtual table curs
2fc30 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  or}.** EXPERIMEN
2fc40 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  TAL.**.** Every 
2fc50 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2fc60 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
2fc70 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
2fc80 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
2fc90 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
2fca0 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20  ure to describe 
2fcb0 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69  cursors that poi
2fcc0 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  nt into the.** [
2fcd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61  virtual table] a
2fce0 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74  nd are used.** t
2fcf0 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74  o loop through t
2fd00 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2fd10 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63  .  Cursors are c
2fd20 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2fd30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  .** [sqlite3_mod
2fd40 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65  ule.xOpen | xOpe
2fd50 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
2fd60 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20   module and are 
2fd70 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20  destroyed.** by 
2fd80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  the [sqlite3_mod
2fd90 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c  ule.xClose | xCl
2fda0 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75  ose] method.  Cu
2fdb0 73 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a  ssors are used.*
2fdc0 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65  * by the [xFilte
2fdd0 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45  r], [xNext], [xE
2fde0 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20  of], [xColumn], 
2fdf0 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74  and [xRowid] met
2fe00 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d  hods.** of the m
2fe10 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64  odule.  Each mod
2fe20 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
2fe30 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a  on will define.*
2fe40 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2fe50 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74   a cursor struct
2fe60 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20  ure to suit its 
2fe70 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  own needs..**.**
2fe80 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   This superclass
2fe90 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72   exists in order
2fea0 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64   to define field
2feb0 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20  s of the cursor 
2fec0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d  that.** are comm
2fed0 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d  on to all implem
2fee0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74  entations..*/.st
2fef0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
2ff00 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c  b_cursor {.  sql
2ff10 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
2ff20 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61  ;      /* Virtua
2ff30 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20  l table of this 
2ff40 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56  cursor */.  /* V
2ff50 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
2ff60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
2ff70 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
2ff80 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
2ff90 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
2ffa0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2ffb0 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41   The Schema Of A
2ffc0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b   Virtual Table {
2ffd0 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e  H18280} <S20400>
2ffe0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2fff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65  .**.** The [xCre
30000 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
30010 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ct] methods of a
30020 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
30030 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20  le module] call 
30040 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a  this interface.*
30050 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
30060 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
30070 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
30080 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
30090 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
300a0 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
300b0 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c  mplement..*/.SQL
300c0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
300d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63   int sqlite3_dec
300e0 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
300f0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
30100 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  zSQL);../*.** CA
30110 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
30120 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
30130 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
30140 7b 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30  {H18300} <S20400
30150 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
30160 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  L.**.** Virtual 
30170 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
30180 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
30190 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
301a0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
301b0 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46  sing the [xFindF
301c0 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20  unction] method 
301d0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
301e0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
301f0 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  .** But global v
30200 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
30210 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
30220 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
30230 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
30240 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ed..**.** This A
30250 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
30260 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
30270 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
30280 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
30290 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
302a0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
302b0 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
302c0 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
302d0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
302e0 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
302f0 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
30300 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68   is created.  Th
30310 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30320 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
30330 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
30340 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
30350 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
30360 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
30370 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
30380 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
30390 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
303a0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
303b0 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
303c0 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  ceholder functio
303d0 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
303e0 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61  erloaded.** by a
303f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
30400 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
30410 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
30420 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75  ite3_overload_fu
30430 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c  nction(sqlite3*,
30440 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
30450 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67  ncName, int nArg
30460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
30470 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
30480 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
30490 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61  hanism defined a
304a0 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a  bove (back up.**
304b0 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65   to a comment re
304c0 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72  markably similar
304d0 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73   to this one) is
304e0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
304f0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
30500 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
30510 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
30520 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
30530 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
30540 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
30550 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
30560 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
30570 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
30580 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
30590 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
305a0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
305b0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
305c0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
305d0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
305e0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
305f0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
30600 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
30610 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  nt..**.****** EX
30620 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
30630 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
30640 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
30650 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a  ************.*/.
30660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30670 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
30680 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30  Open BLOB {H1780
30690 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b  0} <S30230>.** K
306a0 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68  EYWORDS: {BLOB h
306b0 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e  andle} {BLOB han
306c0 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  dles}.**.** An i
306d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
306e0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
306f0 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f  s an open BLOB o
30700 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  n which.** [sqli
30710 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
30720 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
30730 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72   I/O] can be per
30740 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63  formed..** Objec
30750 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
30760 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
30770 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
30780 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
30790 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
307a0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
307b0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
307c0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
307d0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
307e0 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
307f0 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
30800 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
30810 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
30820 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f  tions of the BLO
30830 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  B..** The [sqlit
30840 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
30850 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30860 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
30870 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  he BLOB in bytes
30880 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
30890 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
308a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
308b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
308c0 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
308d0 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20  Incremental I/O 
308e0 7b 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30  {H17810} <S30230
308f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
30900 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
30910 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68  [BLOB handle | h
30920 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c  andle] to the BL
30930 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  OB located.** in
30940 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
30950 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
30960 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
30970 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
30980 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
30990 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77  same BLOB that w
309a0 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
309b0 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
309c0 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
309d0 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
309e0 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f  zTable WHERE [ro
309f0 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20  wid] = iRow;.** 
30a00 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a  </pre> {END}.**.
30a10 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20  ** If the flags 
30a20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
30a30 2d 7a 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42  -zero, the the B
30a40 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
30a50 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
30a60 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69  ite access. If i
30a70 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42  t is zero, the B
30a80 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
30a90 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a  r read access..*
30aa0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
30ab0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
30ac0 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   is not the file
30ad0 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69  name that contai
30ae0 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
30af0 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68  se but rather th
30b00 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
30b10 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
30b20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67  that.** is assig
30b30 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ned when the dat
30b40 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
30b50 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
30b60 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61  ]..** For the ma
30b70 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
30b80 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
30b90 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
30ba0 2a 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  * For TEMP table
30bb0 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  s, the database 
30bc0 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a  name is "temp"..
30bd0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
30be0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
30bf0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
30c00 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
30c10 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
30c20 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
30c30 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
30c40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
30c50 6e 65 64 20 61 6e 64 20 61 6e 79 20 76 61 6c 75  ned and any valu
30c60 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  e written.** to 
30c70 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e  *ppBlob should n
30c80 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68  ot be used by th
30c90 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69  e caller..** Thi
30ca0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
30cb0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30cc0 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
30cd0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
30ce0 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
30cf0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
30d00 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
30d10 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
30d20 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20  *.** If the row 
30d30 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64  that a BLOB hand
30d40 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
30d50 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a  modified by an.*
30d60 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c  * [UPDATE], [DEL
30d70 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20  ETE], or by [ON 
30d80 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65  CONFLICT] side-e
30d90 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74  ffects.** then t
30da0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
30db0 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70  s marked as "exp
30dc0 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69  ired"..** This i
30dd0 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f  s true if any co
30de0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20  lumn of the row 
30df0 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  is changed, even
30e00 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68   a column.** oth
30e10 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  er than the one 
30e20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
30e30 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43  is open on..** C
30e40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30e50 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
30e60 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
30e70 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  write()] for.** 
30e80 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68  a expired BLOB h
30e90 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20  andle fail with 
30ea0 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f  an return code o
30eb0 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
30ec0 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69  ..** Changes wri
30ed0 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42  tten into a BLOB
30ee0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c   prior to the BL
30ef0 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20  OB expiring are 
30f00 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20  not.** rollback 
30f10 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f  by the expiratio
30f20 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20  n of the BLOB.  
30f30 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c  Such changes wil
30f40 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  l eventually.** 
30f50 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72  commit if the tr
30f60 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e  ansaction contin
30f70 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
30f80 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
30f90 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31  ments:.** [H1781
30fa0 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37  3] [H17814] [H17
30fb0 38 31 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48  816] [H17819] [H
30fc0 31 37 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a  17821] [H17824].
30fd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
30fe0 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
30ff0 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
31000 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
31010 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
31020 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
31030 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
31040 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
31050 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
31060 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
31070 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31080 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f  REF: Close A BLO
31090 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30  B Handle {H17830
310a0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
310b0 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20   Closes an open 
310c0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a  [BLOB handle]..*
310d0 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42  *.** Closing a B
310e0 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20  LOB shall cause 
310f0 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e  the current tran
31100 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69  saction to commi
31110 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72  t.** if there ar
31120 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73  e no other BLOBs
31130 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65  , no pending pre
31140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
31150 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74  , and the.** dat
31160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31170 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d   is in [autocomm
31180 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20  it mode]..** If 
31190 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20  any writes were 
311a0 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42  made to the BLOB
311b0 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20  , they might be 
311c0 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a  held in cache.**
311d0 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65   until the close
311e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68   operation if th
311f0 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e  ey will fit. {EN
31200 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67  D}.**.** Closing
31210 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
31220 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
31230 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
31240 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
31250 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
31260 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
31270 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
31280 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
31290 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
312a0 20 20 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 65    {H17833} Any e
312b0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
312c0 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
312d0 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
312e0 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
312f0 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  turn value..**.*
31300 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  * The BLOB is cl
31310 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
31320 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
31330 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
31340 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
31350 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
31360 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a  s still closed..
31370 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
31380 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20  ts:.** [H17833] 
31390 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39  [H17836] [H17839
313a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
313b0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
313c0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
313d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
313e0 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
313f0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48   An Open BLOB {H
31400 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17840} <S30230>.
31410 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68  **.** Returns th
31420 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
31430 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65  of the BLOB acce
31440 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f  ssible via the o
31450 70 65 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 61  pen.** []BLOB ha
31460 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
31470 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  y argument..**.*
31480 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
31490 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69  ** [H17843].*/.i
314a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
314b0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
314c0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
314d0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74  PI3REF: Read Dat
314e0 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
314f0 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37  crementally {H17
31500 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  850} <S30230>.**
31510 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
31520 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  n is used to rea
31530 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f  d data from an o
31540 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
31550 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c  ] into a.** call
31560 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
31570 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
31580 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
31590 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  nto buffer Z.** 
315a0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c  from the open BL
315b0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
315c0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
315d0 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20  **.** If offset 
315e0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
315f0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
31600 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
31610 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
31620 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
31630 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
31640 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20   is read.  If N 
31650 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a  or iOffset is.**
31660 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
31670 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
31680 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
31690 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
316a0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70  .**.** An attemp
316b0 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61  t to read from a
316c0 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
316d0 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
316e0 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
316f0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
31700 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  BORT]..**.** On 
31710 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f  success, SQLITE_
31720 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
31730 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
31740 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
31750 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
31760 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
31770 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  urned..**.** Req
31780 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
31790 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20  17853] [H17856] 
317a0 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32  [H17859] [H17862
317b0 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38  ] [H17863] [H178
317c0 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a  65] [H17868].*/.
317d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
317e0 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c  _read(sqlite3_bl
317f0 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69  ob *, void *Z, i
31800 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt N, int iOffse
31810 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31820 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20  REF: Write Data 
31830 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72  Into A BLOB Incr
31840 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37  ementally {H1787
31850 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
31860 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
31870 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
31880 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
31890 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
318a0 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65   from a.** calle
318b0 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
318c0 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61  r. N bytes of da
318d0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
318e0 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a  om the buffer Z.
318f0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e  ** into the open
31900 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20   BLOB, starting 
31910 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
31920 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
31930 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61  [BLOB handle] pa
31940 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
31950 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e  t argument was n
31960 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a  ot opened for.**
31970 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
31980 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
31990 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
319a0 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29  pen()] was zero)
319b0 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  ,.** this functi
319c0 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
319d0 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a  TE_READONLY]..**
319e0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
319f0 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66  n may only modif
31a00 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  y the contents o
31a10 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69  f the BLOB; it i
31a20 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
31a30 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  e to increase th
31a40 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  e size of a BLOB
31a50 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e   using this API.
31a60 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
31a70 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
31a80 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
31a90 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
31aa0 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
31ab0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
31ac0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
31ad0 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e  s written.  If N
31ae0 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
31af0 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52   zero [SQLITE_ER
31b00 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
31b10 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
31b20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41  written..**.** A
31b30 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69  n attempt to wri
31b40 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64  te to an expired
31b50 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
31b60 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
31b70 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
31b80 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57  QLITE_ABORT].  W
31b90 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f  rites to the BLO
31ba0 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a  B that occurred.
31bb0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42  ** before the [B
31bc0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69  LOB handle] expi
31bd0 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c  red are not roll
31be0 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a  ed back by the.*
31bf0 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  * expiration of 
31c00 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75  the handle, thou
31c10 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f  gh of course tho
31c20 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74  se changes might
31c30 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76  .** have been ov
31c40 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
31c50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
31c60 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42  expired the BLOB
31c70 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79   handle.** or by
31c80 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65   other independe
31c90 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  nt statements..*
31ca0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
31cb0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
31cc0 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
31cd0 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
31ce0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
31cf0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
31d00 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
31d10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
31d20 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20  ts:.** [H17873] 
31d30 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35  [H17874] [H17875
31d40 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38  ] [H17876] [H178
31d50 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31  77] [H17879] [H1
31d60 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a  7882] [H17885].*
31d70 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e  * [H17888].*/.in
31d80 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
31d90 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
31da0 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
31db0 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
31dc0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
31dd0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
31de0 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
31df0 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c  jects {H11200} <
31e00 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20  S20100>.**.** A 
31e10 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
31e20 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
31e30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
31e40 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
31e50 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
31e60 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
31e70 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
31e80 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
31e90 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
31ea0 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
31eb0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
31ec0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
31ed0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
31ee0 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
31ef0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
31f00 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
31f10 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
31f20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
31f30 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
31f40 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
31f50 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
31f60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31f70 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65  _vfs_find() inte
31f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31f90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53  pointer to a VFS
31fa0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
31fb0 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61  .** Names are ca
31fc0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a  se sensitive..**
31fd0 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d   Names are zero-
31fe0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
31ff0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20   strings..** If 
32000 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
32010 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  h, a NULL pointe
32020 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
32030 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73  * If zVfsName is
32040 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
32050 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
32060 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65  turned..**.** Ne
32070 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
32080 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
32090 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
320a0 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20  ()..** Each new 
320b0 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20  VFS becomes the 
320c0 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74  default VFS if t
320d0 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
320e0 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   is set..** The 
320f0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
32100 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
32110 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
32120 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20  t injury..** To 
32130 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67  make an existing
32140 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65   VFS into the de
32150 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73  fault VFS, regis
32160 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20  ter it again.** 
32170 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c  with the makeDfl
32180 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20  t flag set.  If 
32190 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46  two different VF
321a0 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  Ses with the.** 
321b0 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65  same name are re
321c0 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65  gistered, the be
321d0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
321e0 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46  ned.  If a.** VF
321f0 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  S is registered 
32200 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74  with a name that
32210 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
32220 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20  mpty string,.** 
32230 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32240 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
32250 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72  **.** Unregister
32260 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
32270 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
32280 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
32290 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65  ce..** If the de
322a0 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72  fault VFS is unr
322b0 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68  egistered, anoth
322c0 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e  er VFS is chosen
322d0 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   as.** the defau
322e0 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20  lt.  The choice 
322f0 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20  for the new VFS 
32300 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
32310 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
32320 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48  :.** [H11203] [H
32330 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20  11206] [H11209] 
32340 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35  [H11212] [H11215
32350 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71  ] [H11218].*/.sq
32360 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
32370 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
32380 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
32390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
323a0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
323b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
323c0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
323d0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
323e0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
323f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32400 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37  EF: Mutexes {H17
32410 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  000} <S20000>.**
32420 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
32430 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
32440 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
32450 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
32460 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68  ation. Though th
32470 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
32480 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
32490 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
324a0 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
324b0 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
324c0 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
324d0 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
324e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
324f0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
32500 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
32510 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
32520 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
32530 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
32540 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
32550 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
32560 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
32570 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
32580 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
32590 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
325a0 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
325b0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
325c0 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
325d0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
325e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
325f0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
32600 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
32610 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
32620 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
32630 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
32640 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
32650 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
32660 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
32670 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
32680 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
32690 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20   of routines.** 
326a0 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
326b0 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
326c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
326d0 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e   use in.** a sin
326e0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
326f0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
32700 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
32710 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
32720 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
32730 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
32740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
32750 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
32760 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
32770 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
32780 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53  dows..**.** If S
32790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
327a0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
327b0 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70  E_MUTEX_APPDEF p
327c0 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d  reprocessor.** m
327d0 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69  acro defined (wi
327e0 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54  th "-DSQLITE_MUT
327f0 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74  EX_APPDEF=1"), t
32800 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20  hen no mutex.** 
32810 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32820 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  s included with 
32830 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20  the library. In 
32840 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a  this case the.**
32850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
32860 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f  t supply a custo
32870 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  m mutex implemen
32880 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65  tation using the
32890 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
328a0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
328b0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
328c0 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f  config() functio
328d0 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c  n.** before call
328e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ing sqlite3_init
328f0 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20  ialize() or any 
32900 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c  other public sql
32910 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f  ite3_.** functio
32920 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c  n that calls sql
32930 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
32940 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31  )..**.** {H17011
32950 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
32960 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74  tex_alloc() rout
32970 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  ine allocates a 
32980 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64  new.** mutex and
32990 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
329a0 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31  er to it. {H1701
329b0 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  2} If it returns
329c0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65   NULL.** that me
329d0 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78  ans that a mutex
329e0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c   could not be al
329f0 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33  located. {H17013
32a00 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  } SQLite.** will
32a10 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
32a20 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
32a30 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20  error. {H17014} 
32a40 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
32a50 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
32a60 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20  _alloc() is one 
32a70 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
32a80 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a   constants:.**.*
32a90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
32aa0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
32ab0 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  T.** <li>  SQLIT
32ac0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
32ad0 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
32ae0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
32af0 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53  ASTER.** <li>  S
32b00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
32b10 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_MEM.** <li>  
32b20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
32b30 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e  TIC_MEM2.** <li>
32b40 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
32b50 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c  TATIC_PRNG.** <l
32b60 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
32b70 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c  _STATIC_LRU.** <
32b80 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
32b90 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a  X_STATIC_LRU2.**
32ba0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31   </ul>.**.** {H1
32bb0 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20  7015} The first 
32bc0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  two constants ca
32bd0 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
32be0 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
32bf0 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
32c00 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74  ex.  The new mut
32c10 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20  ex is recursive 
32c20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
32c30 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69  X_RECURSIVE.** i
32c40 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e  s used but not n
32c50 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68  ecessarily so wh
32c60 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
32c70 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45  FAST is used. {E
32c80 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ND}.** The mutex
32c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32ca0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
32cb0 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
32cc0 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
32cd0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
32ce0 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
32cf0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
32d00 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
32d10 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d  nt to.  {H17016}
32d20 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c   But SQLite will
32d30 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20   only request a 
32d40 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20  recursive mutex 
32d50 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72  in.** cases wher
32d60 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64  e it really need
32d70 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66  s one.  {END} If
32d80 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
32d90 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
32da0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32db0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
32dc0 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
32dd0 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
32de0 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
32df0 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
32e00 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
32e10 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
32e20 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  FAST..**.** {H17
32e30 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61  017} The other a
32e40 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
32e50 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
32e60 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20  ex_alloc() each 
32e70 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
32e80 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
32e90 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
32ea0 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73  x. {END}  Four s
32eb0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
32ec0 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
32ed0 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
32ee0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
32ef0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
32f00 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
32f10 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
32f20 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
32f30 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
32f40 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
32f50 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
32f60 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
32f70 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
32f80 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
32f90 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
32fa0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
32fb0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
32fc0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
32fd0 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
32fe0 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
32ff0 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74  .** {H17018} Not
33000 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
33010 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
33020 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
33030 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
33040 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
33050 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
33060 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
33070 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
33080 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
33090 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
330a0 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b  n every call.  {
330b0 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20  H17034} But for 
330c0 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
330d0 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
330e0 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
330f0 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
33100 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
33110 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
33120 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  mber..**.** {H17
33130 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33  019} The sqlite3
33140 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
33150 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
33160 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
33170 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
33180 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30  mic mutex. {H170
33190 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61  20} SQLite is ca
331a0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
331b0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
331c0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
331d0 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41  it allocates. {A
331e0 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d  17021} The dynam
331f0 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
33200 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65  not be in.** use
33210 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
33220 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37  eallocated. {A17
33230 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20  022} Attempting 
33240 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
33250 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
33260 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
33270 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b  ined behavior. {
33280 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e  H17023} SQLite n
33290 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
332a0 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
332b0 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ex. {END}.**.** 
332c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
332d0 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71  x_enter() and sq
332e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
332f0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  ) routines attem
33300 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61  pt.** to enter a
33310 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d   mutex. {H17024}
33320 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
33330 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
33340 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
33350 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
33360 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
33370 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
33380 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
33390 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
333a0 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d  E_BUSY. {H17025}
333b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
333c0 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
333d0 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
333e0 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
333f0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
33400 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65  .  {H17026} Mute
33410 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  xes created usin
33420 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  g.** SQLITE_MUTE
33430 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20  X_RECURSIVE can 
33440 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69  be entered multi
33450 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65  ple times by the
33460 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a   same thread..**
33470 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63   {H17027} In suc
33480 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
33490 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
334a0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
334b0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
334c0 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
334d0 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
334e0 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74  .  {A17028} If t
334f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
33500 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
33510 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
33520 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
33530 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
33540 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
33550 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20  ed..** {H17029} 
33560 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
33570 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
33580 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
33590 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
335a0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  exes..**.** Some
335b0 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
335c0 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
335d0 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
335e0 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
335f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
33600 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
33610 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
33620 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
33630 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
33640 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
33650 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
33660 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53    {H17030} The S
33670 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20  QLite core only 
33680 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c  ever uses.** sql
33690 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
336a0 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74   as an optimizat
336b0 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61  ion so this is a
336c0 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69  cceptable behavi
336d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33  or..**.** {H1703
336e0 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
336f0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
33700 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
33710 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
33720 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
33730 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
33740 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20  read.  {A17032} 
33750 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
33760 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
33770 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
33780 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
33790 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ed by the.** cal
337a0 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69  ling thread or i
337b0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
337c0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37  allocated.  {H17
337d0 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  033} SQLite will
337e0 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
337f0 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  her. {END}.**.**
33800 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   If the argument
33810 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
33820 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
33830 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
33840 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
33850 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
33860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
33870 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
33880 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
33890 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
338a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
338b0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
338c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
338d0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
338e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
338f0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
33900 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
33910 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
33920 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
33930 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
33940 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
33950 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
33960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
33970 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
33980 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
33990 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
339a0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
339b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
339c0 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
339d0 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d   Object {H17120}
339e0 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50   <S20130>.** EXP
339f0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
33a00 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
33a10 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65  his structure de
33a20 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65  fines the low-le
33a30 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  vel routines.** 
33a40 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65  used to allocate
33a50 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73   and use mutexes
33a60 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c  ..**.** Usually,
33a70 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
33a80 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
33a90 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53  ns provided by S
33aa0 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66  QLite are.** suf
33ab0 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72  ficient, however
33ac0 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68   the user has th
33ad0 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73  e option of subs
33ae0 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f  tituting a custo
33af0 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  m.** implementat
33b00 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69  ion for speciali
33b10 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20  zed deployments 
33b20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77  or systems for w
33b30 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64  hich SQLite.** d
33b40 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
33b50 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
33b60 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68  mentation. In th
33b70 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65  is case, the use
33b80 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64  r.** creates and
33b90 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e   populates an in
33ba0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
33bb0 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73  tructure to pass
33bc0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
33bd0 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69  onfig() along wi
33be0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  th the [SQLITE_C
33bf0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
33c00 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ion..** Addition
33c10 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63  ally, an instanc
33c20 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
33c30 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
33c40 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20  as an.** output 
33c50 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75  variable when qu
33c60 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65  erying the syste
33c70 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  m for the curren
33c80 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  t mutex.** imple
33c90 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67  mentation, using
33ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
33cb0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70  FIG_GETMUTEX] op
33cc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
33cd0 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
33ce0 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
33cf0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
33d00 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
33d10 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74  t of system init
33d20 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68  ialization by th
33d30 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
33d40 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lize() function.
33d50 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65  .** {H17001} The
33d60 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74   xMutexInit rout
33d70 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c  ine shall be cal
33d80 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  led by SQLite on
33d90 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65  ce for each.** e
33da0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
33db0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
33dc0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  lize()]..**.** T
33dd0 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74  he xMutexEnd met
33de0 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
33df0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
33e00 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
33e10 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68  art of system sh
33e20 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71  utdown by the sq
33e30 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
33e40 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a   function. The.*
33e50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
33e60 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
33e70 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72  is expected to r
33e80 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74  elease all outst
33e90 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72  anding.** resour
33ea0 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ces obtained by 
33eb0 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
33ec0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
33ed0 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20  , especially.** 
33ee0 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62  those obtained b
33ef0 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74  y the xMutexInit
33f00 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33   method. {H17003
33f10 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28  } The xMutexEnd(
33f20 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
33f30 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  hall be invoked 
33f40 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61  once for each ca
33f50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33f60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a  hutdown()]..**.*
33f70 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
33f80 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65  seven methods de
33f90 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
33fa0 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41  ructure (xMutexA
33fb0 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46  lloc,.** xMutexF
33fc0 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72  ree, xMutexEnter
33fd0 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75  , xMutexTry, xMu
33fe0 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78  texLeave, xMutex
33ff0 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74  Held and.** xMut
34000 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65  exNotheld) imple
34010 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ment the followi
34020 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72  ng interfaces (r
34030 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a  espectively):.**
34040 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
34050 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
34060 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69  ex_alloc()] </li
34070 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
34080 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
34090 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
340a0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
340b0 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c  tex_enter()] </l
340c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
340d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
340e0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
340f0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
34100 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c  tex_leave()] </l
34110 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
34120 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
34130 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  d()] </li>.**   
34140 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
34150 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20  utex_notheld()] 
34160 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
34170 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69  *.** The only di
34180 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74  fference is that
34190 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69   the public sqli
341a0 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e  te3_XXX function
341b0 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20  s enumerated.** 
341c0 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69  above silently i
341d0 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61  gnore any invoca
341e0 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20  tions that pass 
341f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
34200 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76  nstead.** of a v
34210 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
34220 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  e. The implement
34230 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65  ations of the me
34240 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a  thods defined.**
34250 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
34260 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69  re are not requi
34270 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68  red to handle th
34280 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73  is case, the res
34290 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69  ults.** of passi
342a0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
342b0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76  r instead of a v
342c0 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
342d0 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a  e are undefined.
342e0 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61  ** (i.e. it is a
342f0 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f  cceptable to pro
34300 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  vide an implemen
34310 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66  tation that segf
34320 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69  aults if.** it i
34330 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20  s passed a NULL 
34340 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70  pointer)..*/.typ
34350 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
34360 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
34370 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  s sqlite3_mutex_
34380 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
34390 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
343a0 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a  thods {.  int (*
343b0 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64  xMutexInit)(void
343c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
343d0 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73  xEnd)(void);.  s
343e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a  qlite3_mutex *(*
343f0 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74  xMutexAlloc)(int
34400 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
34410 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f  exFree)(sqlite3_
34420 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
34430 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28   (*xMutexEnter)(
34440 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
34450 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
34460 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  Try)(sqlite3_mut
34470 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
34480 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c  xMutexLeave)(sql
34490 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
344a0 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c   int (*xMutexHel
344b0 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d)(sqlite3_mutex
344c0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
344d0 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69  texNotheld)(sqli
344e0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b  te3_mutex *);.};
344f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34500 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61  : Mutex Verifica
34510 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48  tion Routines {H
34520 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20  17080} <S20130> 
34530 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
34540 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
34550 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69  _held() and sqli
34560 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
34570 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  d() routines.** 
34580 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
34590 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65   use inside asse
345a0 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e  rt() statements.
345b0 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51   {H17081} The SQ
345c0 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
345d0 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
345e0 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
345f0 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
34600 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
34610 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
34620 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
34630 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
34640 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63    {H17082} The c
34650 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
34660 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
34670 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
34680 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
34690 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
346a0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
346b0 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37  EBUG flag.  {A17
346c0 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75  087} External mu
346d0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
346e0 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20  ons.** are only 
346f0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
34700 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ide these routin
34710 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42  es if SQLITE_DEB
34720 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64  UG is.** defined
34730 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69   and if NDEBUG i
34740 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a  s not defined..*
34750 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68  *.** {H17083} Th
34760 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
34770 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
34780 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
34790 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
347a0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
347b0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
347c0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
347d0 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
347e0 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69  * {X17084} The i
347f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
34800 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
34810 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
34820 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
34830 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
34840 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74  ually work. If t
34850 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34860 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  n does not provi
34870 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65  de working.** ve
34880 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20  rsions of these 
34890 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f  routines, it sho
348a0 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f  uld at least pro
348b0 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20  vide stubs that 
348c0 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e  always.** return
348d0 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e   true so that on
348e0 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73  e does not get s
348f0 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f  purious assertio
34900 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a  n failures..**.*
34910 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68  * {H17085} If th
34920 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
34930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
34940 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
34950 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
34960 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
34970 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d  return 1.  {END}
34980 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
34990 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
349a0 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
349b0 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
349c0 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
349d0 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
349e0 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
349f0 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
34a00 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
34a10 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
34a20 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
34a30 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
34a40 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
34a50 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
34a60 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
34a70 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
34a80 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
34a90 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
34aa0 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
34ab0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
34ac0 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48  thing to do.  {H
34ad0 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74  17086} The sqlit
34ae0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
34af0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
34b00 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
34b10 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
34b20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
34b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
34b40 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
34b50 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
34b60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
34b70 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
34b80 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
34b90 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70  I3REF: Mutex Typ
34ba0 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37  es {H17001} <H17
34bb0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  000>.**.** The [
34bc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
34bd0 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
34be0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
34bf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
34c00 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
34c10 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
34c20 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
34c30 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74  et of static mut
34c40 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20  exes may change 
34c50 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20  from one SQLite 
34c60 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a  release to the.*
34c70 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
34c80 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72  tions that overr
34c90 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  ide the built-in
34ca0 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73   mutex logic mus
34cb0 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  t be.** prepared
34cc0 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20   to accommodate 
34cd0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
34ce0 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64  c mutexes..*/.#d
34cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34d00 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
34d10 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
34d20 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
34d30 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
34d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34d50 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
34d60 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
34d70 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
34d80 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
34d90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
34da0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
34db0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
34dc0 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
34dd0 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64  * NOT USED */.#d
34de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34df0 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20  EX_STATIC_OPEN  
34e00 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
34e10 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a  3BtreeOpen() */.
34e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
34e30 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
34e40 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
34e50 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
34e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
34e70 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
34e80 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
34e90 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65  page list */.#de
34ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
34eb0 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20  X_STATIC_LRU2   
34ec0 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67     7  /* lru pag
34ed0 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  e list */../*.**
34ee0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
34ef0 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f  eve the mutex fo
34f00 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
34f10 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d  nection {H17002}
34f20 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H17000>.**.** 
34f30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
34f40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
34f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
34f60 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  tex] object that
34f70 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20   .** serializes 
34f80 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64  access to the [d
34f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34fa0 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65  on] given in the
34fb0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65   argument.** whe
34fc0 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  n the [threading
34fd0 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c   mode] is Serial
34fe0 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ized..** If the 
34ff0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
35000 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   is Single-threa
35010 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61  d or Multi-threa
35020 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72  d then this.** r
35030 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
35040 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
35050 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
35060 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  *sqlite3_db_mute
35070 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  x(sqlite3*);../*
35080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
35090 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
350a0 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
350b0 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38  s {H11300} <S308
350c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  00>.**.** {H1130
350d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
350e0 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
350f0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
35100 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f  a direct call to
35110 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e   the.** xFileCon
35120 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20  trol method for 
35130 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
35140 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
35150 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
35160 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
35170 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66  database identif
35180 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
35190 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31  d argument. {H11
351a0 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65  302} The.** name
351b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
351c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73   is the name ass
351d0 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74  igned to the dat
351e0 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20  abase by the.** 
351f0 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74  <a href="lang_at
35200 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43  tach.html">ATTAC
35210 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e  H</a> SQL comman
35220 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68  d that opened th
35230 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b  e.** database. {
35240 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72  H11303} To contr
35250 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  ol the main data
35260 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74  base file, use t
35270 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a  he name "main".*
35280 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * or a NULL poin
35290 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68  ter. {H11304} Th
352a0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
352b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
352c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
352d0 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65   are passed dire
352e0 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20  ctly through to 
352f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
35300 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20  hird parameters 
35310 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43  of.** the xFileC
35320 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20  ontrol method.  
35330 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74  {H11305} The ret
35340 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
35350 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a   xFileControl.**
35360 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20   method becomes 
35370 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35380 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
35390 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d  ..**.** {H11306}
353a0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
353b0 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
353c0 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
353d0 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
353e0 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
353f0 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
35400 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
35410 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d  turned. {H11307}
35420 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63   This error.** c
35430 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d  ode is not remem
35440 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e  bered and will n
35450 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62  ot be recalled b
35460 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
35470 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  de()].** or [sql
35480 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20  ite3_errmsg()]. 
35490 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64  {A11308} The und
354a0 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
354b0 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
354c0 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
354d0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
354e0 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69  {A11309} There i
354f0 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74  s no way to dist
35500 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a  inguish between.
35510 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20  ** an incorrect 
35520 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53  zDbName and an S
35530 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75  QLITE_ERROR retu
35540 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  rn from the unde
35550 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43  rlying.** xFileC
35560 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b  ontrol method. {
35570 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  END}.**.** See a
35580 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  lso: [SQLITE_FCN
35590 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f  TL_LOCKSTATE].*/
355a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  .int sqlite3_fil
355b0 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65  e_control(sqlite
355c0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
355d0 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c  zDbName, int op,
355e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
355f0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e  CAPI3REF: Testin
35600 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31  g Interface {H11
35610 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  400} <S30800>.**
35620 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
35630 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69  test_control() i
35640 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
35650 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74   to read out int
35660 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f  ernal.** state o
35670 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20  f SQLite and to 
35680 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e  inject faults in
35690 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65  to SQLite for te
356a0 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65  sting.** purpose
356b0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
356c0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70  rameter is an op
356d0 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61  eration code tha
356e0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
356f0 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e  the number, mean
35700 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69  ing, and operati
35710 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71  on of all subseq
35720 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e  uent parameters.
35730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
35740 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72  rface is not for
35750 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74   use by applicat
35760 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73  ions.  It exists
35770 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76   solely.** for v
35780 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72  erifying the cor
35790 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f  rect operation o
357a0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
357b0 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67  rary.  Depending
357c0 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53  .** on how the S
357d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73  QLite library is
357e0 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20   compiled, this 
357f0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
35800 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a  not exist..**.**
35810 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
35820 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f  the operation co
35830 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69  des, their meani
35840 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74  ngs, the paramet
35850 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65  ers.** they take
35860 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20  , and what they 
35870 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65  do are all subje
35880 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
35890 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20  hout notice..** 
358a0 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74  Unlike most of t
358b0 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74  he SQLite API, t
358c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
358d0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
358e0 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e  o.** operate con
358f0 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f  sistently from o
35900 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
35910 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73  e next..*/.int s
35920 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74  qlite3_test_cont
35930 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  rol(int op, ...)
35940 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35950 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72  F: Testing Inter
35960 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43  face Operation C
35970 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48  odes {H11410} <H
35980 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11400>.**.** The
35990 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
359a0 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61   the valid opera
359b0 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65  tion code parame
359c0 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20  ters used.** as 
359d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
359e0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
359f0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a  est_control()]..
35a00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61  **.** These para
35a10 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72  meters and their
35a20 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75   meanings are su
35a30 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a  bject to change.
35a40 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ** without notic
35a50 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73  e.  These values
35a60 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67   are for testing
35a70 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a   purposes only..
35a80 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
35a90 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61  should not use a
35aa0 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  ny of these para
35ab0 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a  meters or the.**
35ac0 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63   [sqlite3_test_c
35ad0 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
35ae0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
35af0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
35b00 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20  PRNG_SAVE       
35b10 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
35b20 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
35b30 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20  RL_PRNG_RESTORE 
35b40 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
35b50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
35b60 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54  TCTRL_PRNG_RESET
35b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
35b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35b90 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f  TESTCTRL_BITVEC_
35ba0 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20  TEST            
35bb0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
35bc0 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c  TE_TESTCTRL_FAUL
35bd0 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20  T_INSTALL       
35be0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
35bf0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42  QLITE_TESTCTRL_B
35c00 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f  ENIGN_MALLOC_HOO
35c10 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e  KS     10.#defin
35c20 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
35c30 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20  L_PENDING_BYTE  
35c40 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
35c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
35c60 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61  Lite Runtime Sta
35c70 74 75 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36  tus {H17200} <S6
35c80 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
35c90 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ENTAL.**.** This
35ca0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
35cb0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72  ed to retrieve r
35cc0 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e  untime status in
35cd0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
35ce0 75 74 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e  ut the preforman
35cf0 63 65 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e  ce of SQLite, an
35d00 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20  d optionally to 
35d10 72 65 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a  reset various.**
35d20 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73   highwater marks
35d30 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
35d40 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
35d50 67 65 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20  ger code for.** 
35d60 74 68 65 20 73 70 65 63 69 66 69 63 20 70 61 72  the specific par
35d70 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72  ameter to measur
35d80 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69  e.  Recognized i
35d90 6e 74 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20  nteger codes.** 
35da0 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  are of the form 
35db0 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d  [SQLITE_STATUS_M
35dc0 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c  EMORY_USED | SQL
35dd0 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e  ITE_STATUS_...].
35de0 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20  .** The current 
35df0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72  value of the par
35e00 61 6d 65 74 65 72 20 69 73 20 72 65 74 75 72 6e  ameter is return
35e10 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e  ed into *pCurren
35e20 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73  t..** The highes
35e30 74 20 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65  t recorded value
35e40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20   is returned in 
35e50 2a 70 48 69 67 68 77 61 74 65 72 2e 20 20 49 66  *pHighwater.  If
35e60 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61   the.** resetFla
35e70 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  g is true, then 
35e80 74 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f  the highest reco
35e90 72 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 65  rd value is rese
35ea0 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67  t after.** *pHig
35eb0 68 77 61 74 65 72 20 69 73 20 77 72 69 74 74 65  hwater is writte
35ec0 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65  n. Some paramete
35ed0 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64  rs do not record
35ee0 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20   the highest.** 
35ef0 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73  value.  For thos
35f00 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
35f10 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 74  nothing is writt
35f20 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61  en into *pHighwa
35f30 74 65 72 20 61 6e 64 20 74 68 65 20 72 65 73 65  ter and the rese
35f40 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64  tFlag is ignored
35f50 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d  ..** Other param
35f60 65 74 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c  eters record onl
35f70 79 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20  y the highwater 
35f80 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65  mark and not the
35f90 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75   current.** valu
35fa0 65 2e 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61  e.  For these la
35fb0 74 74 65 72 20 70 61 72 61 6d 65 74 65 72 73 20  tter parameters 
35fc0 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74 74  nothing is writt
35fd0 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e  en into *pCurren
35fe0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  t..**.** This ro
35ff0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
36000 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
36010 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72  ss and a non-zer
36020 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  o.** [error code
36030 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
36040 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
36050 20 69 73 20 74 68 72 65 61 64 73 61 66 65 20 62   is threadsafe b
36060 75 74 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63  ut is not atomic
36070 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
36080 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68  can.** called wh
36090 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61 64  ile other thread
360a0 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 68  s are running th
360b0 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65 72  e same or differ
360c0 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  ent SQLite.** in
360d0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
360e0 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  er the values re
360f0 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 72  turned in *pCurr
36100 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67  ent and.** *pHig
36110 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20 74  hwater reflect t
36120 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51 4c  he status of SQL
36130 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e 74  ite at different
36140 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a   points in time.
36150 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f 73  ** and it is pos
36160 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  sible that anoth
36170 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74 20  er thread might 
36180 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61 6d  change the param
36190 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65  eter.** in betwe
361a0 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68 65  en the times whe
361b0 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 20  n *pCurrent and 
361c0 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65 20  *pHighwater are 
361d0 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53  written..**.** S
361e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
361f0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a 2a  3_db_status()].*
36200 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
36210 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
36220 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70 2c  3_status(int op,
36230 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c 20   int *pCurrent, 
36240 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72 2c  int *pHighwater,
36250 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b   int resetFlag);
36260 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
36270 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65  F: Status Parame
36280 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c 48  ters {H17250} <H
36290 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  17200>.** EXPERI
362a0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
362b0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
362c0 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20 76  ants designate v
362d0 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 20  arious run-time 
362e0 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 72  status parameter
362f0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
36300 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
36310 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 2e  lite3_status()].
36320 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
36330 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53  dt>SQLITE_STATUS
36340 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 74  _MEMORY_USED</dt
36350 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36360 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63  rameter is the c
36370 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f 66  urrent amount of
36380 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 20   memory checked 
36390 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  out.** using [sq
363a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
363b0 20 65 69 74 68 65 72 20 64 69 72 65 63 74 6c 79   either directly
363c0 20 6f 72 20 69 6e 64 69 72 65 63 74 6c 79 2e 20   or indirectly. 
363d0 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 69   The.** figure i
363e0 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d 61  ncludes calls ma
363f0 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  de to [sqlite3_m
36400 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 20  alloc()] by the 
36410 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 61  application.** a
36420 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  nd internal memo
36430 72 79 20 75 73 61 67 65 20 62 79 20 74 68 65 20  ry usage by the 
36440 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
36450 20 53 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a   Scratch memory.
36460 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  ** controlled by
36470 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
36480 53 43 52 41 54 43 48 5d 20 61 6e 64 20 61 75 78  SCRATCH] and aux
36490 69 6c 69 61 72 79 20 70 61 67 65 2d 63 61 63 68  iliary page-cach
364a0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e 74  e.** memory cont
364b0 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54  rolled by [SQLIT
364c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
364d0 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  HE] is not inclu
364e0 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 70  ded in.** this p
364f0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 61  arameter.  The a
36500 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 69  mount returned i
36510 73 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65  s the sum of the
36520 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73   allocation.** s
36530 69 7a 65 73 20 61 73 20 72 65 70 6f 72 74 65 64  izes as reported
36540 20 62 79 20 74 68 65 20 78 53 69 7a 65 20 6d 65   by the xSize me
36550 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 33  thod in [sqlite3
36560 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f  _mem_methods].</
36570 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
36580 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c  LITE_STATUS_MALL
36590 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  OC_SIZE</dt>.** 
365a0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
365b0 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  er records the l
365c0 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c  argest memory al
365d0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
365e0 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  .** handed to [s
365f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
36600 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
36610 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 69  lloc()] (or thei
36620 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 71  r.** internal eq
36630 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c  uivalents).  Onl
36640 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  y the value retu
36650 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a  rned in the.** *
36660 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d  pHighwater param
36670 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
36680 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66  _status()] is of
36690 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20   interest.  .** 
366a0 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65  The value writte
366b0 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72  n into the *pCur
366c0 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69  rent parameter i
366d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  s undefined.</dd
366e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
366f0 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
36700 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a  CHE_USED</dt>.**
36710 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
36720 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20  ter returns the 
36730 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
36740 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a  used out of the.
36750 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65  ** [pagecache me
36760 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
36770 74 68 61 74 20 77 61 73 20 63 6f 6e 66 69 67 75  that was configu
36780 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 53  red using .** [S
36790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
367a0 45 43 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a 2a  ECACHE].  The.**
367b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
367c0 69 73 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f 74  is in pages, not
367d0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 0a   in bytes.</dd>.
367e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
367f0 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48  _STATUS_PAGECACH
36800 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a  E_OVERFLOW</dt>.
36810 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
36820 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
36830 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36840 73 20 6f 66 20 70 61 67 65 20 63 61 63 68 65 0a  s of page cache.
36850 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68  ** allocation wh
36860 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  ich could not be
36870 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74   statisfied by t
36880 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
36890 47 5f 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a 20  G_PAGECACHE].** 
368a0 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 65  buffer and where
368b0 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66   forced to overf
368c0 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  low to [sqlite3_
368d0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 0a  malloc()].  The.
368e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  ** returned valu
368f0 65 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f 63  e includes alloc
36900 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
36910 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 20 74  flowed because t
36920 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f 6f  hey.** where too
36930 20 6c 61 72 67 65 20 28 74 68 65 79 20 77 65 72   large (they wer
36940 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
36950 65 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72  e "sz" parameter
36960 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   to.** [SQLITE_C
36970 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
36980 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f 6e  ) and allocation
36990 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65  s that overflowe
369a0 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f 20  d because.** no 
369b0 73 70 61 63 65 20 77 61 73 20 6c 65 66 74 20 69  space was left i
369c0 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  n the page cache
369d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
369e0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50  >SQLITE_STATUS_P
369f0 41 47 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f 64  AGECACHE_SIZE</d
36a00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
36a10 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73  arameter records
36a20 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d   the largest mem
36a30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
36a40 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64  equest.** handed
36a50 20 74 6f 20 5b 70 61 67 65 63 61 63 68 65 20 6d   to [pagecache m
36a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
36a70 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75  .  Only the valu
36a80 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68  e returned in th
36a90 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72  e.** *pHighwater
36aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
36ab0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
36ac0 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e   is of interest.
36ad0 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20    .** The value 
36ae0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
36af0 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d   *pCurrent param
36b00 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65  eter is undefine
36b10 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
36b20 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
36b30 53 43 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 74  SCRATCH_USED</dt
36b40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61  >.** <dd>This pa
36b50 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20  rameter returns 
36b60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 6c  the number of al
36b70 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 64 20 6f  locations used o
36b80 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 63  ut of the.** [sc
36b90 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
36ba0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
36bb0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c  ed using.** [SQL
36bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
36bd0 43 48 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20  CH].  The value 
36be0 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61  returned is in a
36bf0 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a  llocations, not.
36c00 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69  ** in bytes.  Si
36c10 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72  nce a single thr
36c20 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76  ead may only hav
36c30 65 20 6f 6e 65 20 73 63 72 61 74 63 68 20 61 6c  e one scratch al
36c40 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73  location.** outs
36c50 74 61 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 2c  tanding at time,
36c60 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
36c70 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 74 68 65  also reports the
36c80 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
36c90 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 61  ds.** using scra
36ca0 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 68  tch memory at th
36cb0 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64  e same time.</dd
36cc0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36cd0 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
36ce0 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a  H_OVERFLOW</dt>.
36cf0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
36d00 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
36d10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36d20 73 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  s of scratch mem
36d30 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
36d40 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f  n which could no
36d50 74 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20  t be statisfied 
36d60 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  by the [SQLITE_C
36d70 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 0a 2a  ONFIG_SCRATCH].*
36d80 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 65  * buffer and whe
36d90 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65  re forced to ove
36da0 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65  rflow to [sqlite
36db0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
36dc0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 75  e values.** retu
36dd0 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 65  rned include ove
36de0 72 66 6c 6f 77 73 20 62 65 63 61 75 73 65 20 74  rflows because t
36df0 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c  he requested all
36e00 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f 0a  ocation was too.
36e10 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 61 74 20  ** larger (that 
36e20 69 73 2c 20 62 65 63 61 75 73 65 20 74 68 65 20  is, because the 
36e30 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61  requested alloca
36e40 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 20  tion was larger 
36e50 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a 22  than the.** "sz"
36e60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 53   parameter to [S
36e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
36e80 41 54 43 48 5d 29 20 61 6e 64 20 62 65 63 61 75  ATCH]) and becau
36e90 73 65 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75  se no scratch bu
36ea0 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 65  ffer.** slots we
36eb0 72 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  re available..**
36ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
36ed0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53  >SQLITE_STATUS_S
36ee0 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 3e  CRATCH_SIZE</dt>
36ef0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
36f00 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74  ameter records t
36f10 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72  he largest memor
36f20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
36f30 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74  uest.** handed t
36f40 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  o [scratch memor
36f50 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f  y allocator].  O
36f60 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
36f70 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
36f80 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
36f90 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
36fa0 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
36fb0 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
36fc0 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
36fd0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
36fe0 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
36ff0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
37000 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
37010 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53  LITE_STATUS_PARS
37020 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a  ER_STACK</dt>.**
37030 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
37040 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20  ter records the 
37050 64 65 65 70 65 73 74 20 70 61 72 73 65 72 20 73  deepest parser s
37060 74 61 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e 6c  tack.  It is onl
37070 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c 20  y.** meaningful 
37080 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
37090 70 69 6c 65 64 20 77 69 74 68 20 5b 59 59 54 52  piled with [YYTR
370a0 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 48  ACKMAXSTACKDEPTH
370b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  ].</dd>.** </dl>
370c0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 75  .**.** New statu
370d0 73 20 70 61 72 61 6d 65 74 65 72 73 20 6d 61 79  s parameters may
370e0 20 62 65 20 61 64 64 65 64 20 66 72 6f 6d 20 74   be added from t
370f0 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a  ime to time..*/.
37100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
37110 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45  TATUS_MEMORY_USE
37120 44 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  D          0.#de
37130 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
37140 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45  US_PAGECACHE_USE
37150 44 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  D       1.#defin
37160 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
37170 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c  PAGECACHE_OVERFL
37180 4f 57 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  OW   2.#define S
37190 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52  QLITE_STATUS_SCR
371a0 41 54 43 48 5f 55 53 45 44 20 20 20 20 20 20 20  ATCH_USED       
371b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
371c0 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
371d0 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 34  H_OVERFLOW     4
371e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
371f0 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49  STATUS_MALLOC_SI
37200 5a 45 20 20 20 20 20 20 20 20 20 20 35 0a 23 64  ZE          5.#d
37210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
37220 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b  TUS_PARSER_STACK
37230 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
37240 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
37250 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 20  _PAGECACHE_SIZE 
37260 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
37270 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43  SQLITE_STATUS_SC
37280 52 41 54 43 48 5f 53 49 5a 45 20 20 20 20 20 20  RATCH_SIZE      
37290 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
372a0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
372b0 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 73  onnection Status
372c0 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 30 32 30   {H17500} <S6020
372d0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
372e0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  AL.**.** This in
372f0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
37300 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74  to retrieve runt
37310 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72  ime status infor
37320 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74  mation .** about
37330 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 62   a single [datab
37340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
37350 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
37360 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 64  ment is the.** d
37370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37380 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20  on object to be 
37390 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
373a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
373b0 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 72  nt.** is the par
373c0 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 65 72 72  ameter to interr
373d0 6f 67 61 74 65 2e 20 20 43 75 72 72 65 6e 74 6c  ogate.  Currentl
373e0 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f  y, the only allo
373f0 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f 72  wed value.** for
37400 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
37410 6d 65 74 65 72 20 69 73 20 5b 53 51 4c 49 54 45  meter is [SQLITE
37420 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53  _DBSTATUS_LOOKAS
37430 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 64  IDE_USED]..** Ad
37440 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73  ditional options
37450 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 70   will likely app
37460 65 61 72 20 69 6e 20 66 75 74 75 72 65 20 72 65  ear in future re
37470 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
37480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 72  ..**.** The curr
37490 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ent value of the
374a0 20 72 65 71 75 65 73 74 65 64 20 70 61 72 61 6d   requested param
374b0 65 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  eter is written 
374c0 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 6e  into *pCur.** an
374d0 64 20 74 68 65 20 68 69 67 68 65 73 74 20 69 6e  d the highest in
374e0 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75  stantaneous valu
374f0 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
37500 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 66 0a 2a  o *pHiwtr.  If.*
37510 2a 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 69  * the resetFlg i
37520 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
37530 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74   highest instant
37540 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 0a  aneous value is.
37550 2a 2a 20 72 65 73 65 74 20 62 61 63 6b 20 64 6f  ** reset back do
37560 77 6e 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  wn to the curren
37570 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53  t value..**.** S
37580 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
37590 33 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20  3_status()] and 
375a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74  [sqlite3_stmt_st
375b0 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  atus()]..*/.SQLI
375c0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
375d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 73  int sqlite3_db_s
375e0 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a 2c 20  tatus(sqlite3*, 
375f0 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75  int op, int *pCu
37600 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 2c 20  r, int *pHiwtr, 
37610 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a  int resetFlg);..
37620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37630 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72  Status Parameter
37640 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 20 63  s for database c
37650 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37 35  onnections {H175
37660 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 20  20} <H17500>.** 
37670 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
37680 2a 2a 20 53 74 61 74 75 73 20 76 65 72 62 73 20  ** Status verbs 
37690 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  for [sqlite3_db_
376a0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  status()]..**.**
376b0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
376c0 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f  ITE_DBSTATUS_LOO
376d0 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 3e  KASIDE_USED</dt>
376e0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
376f0 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74  ameter returns t
37700 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f 6f  he number of loo
37710 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 6c  kaside memory sl
37720 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  ots currently.**
37730 20 63 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f 64   checked out.</d
37740 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d>.** </dl>.*/.#
37750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
37760 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45  STATUS_LOOKASIDE
37770 5f 55 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f 2a  _USED     0.../*
37780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
37790 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
377a0 20 53 74 61 74 75 73 20 7b 48 31 37 35 35 30 7d   Status {H17550}
377b0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50   <S60200>.** EXP
377c0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
377d0 45 61 63 68 20 70 72 65 70 61 72 65 64 20 73 74  Each prepared st
377e0 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 6e  atement maintain
377f0 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 51  s various.** [SQ
37800 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f  LITE_STMTSTATUS_
37810 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 5d  SORT | counters]
37820 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74 68   that measure th
37830 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74  e number.** of t
37840 69 6d 65 73 20 69 74 20 68 61 73 20 70 65 72 66  imes it has perf
37850 6f 72 6d 65 64 20 73 70 65 63 69 66 69 63 20 6f  ormed specific o
37860 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 73  perations.  Thes
37870 65 20 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a 2a  e counters can.*
37880 2a 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f 6e  * be used to mon
37890 69 74 6f 72 20 74 68 65 20 70 65 72 66 6f 72 6d  itor the perform
378a0 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 69 73  ance characteris
378b0 74 69 63 73 20 6f 66 20 74 68 65 20 70 72 65 70  tics of the prep
378c0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
378d0 74 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ts.  For example
378e0 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72 20  , if the number 
378f0 6f 66 20 74 61 62 6c 65 20 73 74 65 70 73 20 67  of table steps g
37900 72 65 61 74 6c 79 20 65 78 63 65 65 64 73 0a 2a  reatly exceeds.*
37910 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
37920 74 61 62 6c 65 20 73 65 61 72 63 68 65 73 20 6f  table searches o
37930 72 20 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 74  r result rows, t
37940 68 61 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 74  hat would tend t
37950 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 68  o indicate.** th
37960 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
37970 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 69  statement is usi
37980 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20  ng a full table 
37990 73 63 61 6e 20 72 61 74 68 65 72 20 74 68 61 6e  scan rather than
379a0 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 0a  .** an index.  .
379b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
379c0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
379d0 72 65 74 72 69 65 76 65 20 61 6e 64 20 72 65 73  retrieve and res
379e0 65 74 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 65  et counter value
379f0 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65  s from.** a [pre
37a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37a10 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
37a20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 70 72 65  ument is the pre
37a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37a40 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20  ** object to be 
37a50 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
37a60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37a70 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  nt.** is an inte
37a80 67 65 72 20 63 6f 64 65 20 66 6f 72 20 61 20 73  ger code for a s
37a90 70 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f  pecific [SQLITE_
37aa0 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20  STMTSTATUS_SORT 
37ab0 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f  | counter].** to
37ac0 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64   be interrogated
37ad0 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  . .** The curren
37ae0 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72  t value of the r
37af0 65 71 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72  equested counter
37b00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
37b10 20 49 66 20 74 68 65 20 72 65 73 65 74 46 6c 67   If the resetFlg
37b20 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
37b30 68 65 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65  he counter is re
37b40 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 65  set to zero afte
37b50 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
37b60 61 63 65 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ace call returns
37b70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37b80 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  : [sqlite3_statu
37b90 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
37ba0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a  3_db_status()]..
37bb0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
37bc0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
37bd0 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73  e3_stmt_status(s
37be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
37bf0 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c  t op,int resetFl
37c00 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
37c10 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61  REF: Status Para
37c20 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 70 61  meters for prepa
37c30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b  red statements {
37c40 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e  H17570} <H17550>
37c50 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
37c60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65  .**.** These pre
37c70 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
37c80 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
37c90 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20  codes that name 
37ca0 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65  counter.** value
37cb0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
37cc0 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  h the [sqlite3_s
37cd0 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e  tmt_status()] in
37ce0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20  terface..** The 
37cf0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
37d00 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73  various counters
37d10 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   are as follows:
37d20 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
37d30 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54  dt>SQLITE_STMTST
37d40 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54  ATUS_FULLSCAN_ST
37d50 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  EP</dt>.** <dd>T
37d60 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65  his is the numbe
37d70 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
37d80 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70 70  SQLite has stepp
37d90 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a  ed forward in.**
37da0 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72 74   a table as part
37db0 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65   of a full table
37dc0 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75   scan.  Large nu
37dd0 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20 63  mbers for this c
37de0 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e  ounter.** may in
37df0 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69  dicate opportuni
37e00 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  ties for perform
37e10 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74  ance improvement
37e20 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72   through .** car
37e30 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69  eful use of indi
37e40 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ces.</dd>.**.** 
37e50 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53  <dt>SQLITE_STMTS
37e60 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a  TATUS_SORT</dt>.
37e70 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74  ** <dd>This is t
37e80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72  he number of sor
37e90 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61  t operations tha
37ea0 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e  t have occurred.
37eb0 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76  .** A non-zero v
37ec0 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75  alue in this cou
37ed0 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74  nter may indicat
37ee0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
37ef0 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65   to.** improveme
37f00 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74  nt performance t
37f10 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75  hrough careful u
37f20 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f  se of indices.</
37f30 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
37f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37f50 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c  E_STMTSTATUS_FUL
37f60 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31  LSCAN_STEP     1
37f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f80 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20  STMTSTATUS_SORT 
37f90 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a               2..
37fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37fb0 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68  Custom Page Cach
37fc0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45  e Object.** EXPE
37fd0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
37fe0 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  he sqlite3_pcach
37ff0 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 75 65  e type is opaque
38000 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65  .  It is impleme
38010 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  nted by.** the p
38020 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e  luggable module.
38030 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
38040 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64  e has no knowled
38050 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a  ge of.** its siz
38060 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74  e or internal st
38070 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65  ructure and neve
38080 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 68 65  r deals with the
38090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63  .** sqlite3_pcac
380a0 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74  he object except
380b0 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20   by holding and 
380c0 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73  passing pointers
380d0 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63  .** to the objec
380e0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71  t..**.** See [sq
380f0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
38100 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69  hods] for additi
38110 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
38120 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
38130 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63  uct sqlite3_pcac
38140 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  he sqlite3_pcach
38150 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
38160 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  EF: Application 
38170 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 61 63  Defined Page Cac
38180 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  he..** EXPERIMEN
38190 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  TAL.**.** The [s
381a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
381b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
381c0 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65  ACHE], ...) inte
381d0 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67  rface can.** reg
381e0 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e 61  ister an alterna
381f0 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20  tive page cache 
38200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62  implementation b
38210 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e 20  y passing in an 
38220 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
38230 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63  the sqlite3_pcac
38240 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 63  he_methods struc
38250 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69  ture. The majori
38260 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65  ty of the .** he
38270 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62  ap memory used b
38280 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 65 64  y sqlite is used
38290 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63   by the page cac
382a0 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  he to cache data
382b0 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20   read .** from, 
382c0 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 20 77  or ready to be w
382d0 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 64  ritten to, the d
382e0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79  atabase file. By
382f0 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20   implementing a 
38300 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 20  .** custom page 
38310 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 69 73  cache using this
38320 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 61   API, an applica
38330 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c  tion can control
38340 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 73   more .** precis
38350 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  ely the amount o
38360 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65  f memory consume
38370 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68 65  d by sqlite, the
38380 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a   way in which .*
38390 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 73  * said memory is
383a0 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72   allocated and r
383b0 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65  eleased, and the
383c0 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74   policies used t
383d0 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20  o .** determine 
383e0 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 70 61  exactly which pa
383f0 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 61 73  rts of a databas
38400 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 68 65  e file are cache
38410 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f  d and for .** ho
38420 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  w long..**.** Th
38430 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
38440 65 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20  e structure are 
38450 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e 74  copied to an int
38460 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79 20  ernal buffer by 
38470 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e  sqlite.** within
38480 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71   the call to [sq
38490 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a  lite3_config]..*
384a0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 29  *.** The xInit()
384b0 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65   method is calle
384c0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
384d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
384e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 2a  _initialize()].*
384f0 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 20  * (usually only 
38500 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  once during the 
38510 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
38520 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73 20  process). It is 
38530 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 79  passed.** a copy
38540 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
38550 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e 70  pcache_methods.p
38560 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63 61  Arg value. It ca
38570 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74  n be used to set
38580 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 74  .** up global st
38590 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75 74  ructures and mut
385a0 65 78 65 73 20 72 65 71 75 69 72 65 64 20 62 79  exes required by
385b0 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67 65   the custom page
385c0 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c 65   cache .** imple
385d0 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 78  mentation. The x
385e0 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f  Shutdown() metho
385f0 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f 6d  d is called from
38600 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c   within .** [sql
38610 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
38620 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61  , if the applica
38630 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 69  tion invokes thi
38640 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 65  s API. It can be
38650 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 61   used.** to clea
38660 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61 6e  n up any outstan
38670 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20 62  ding resources b
38680 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73 68  efore process sh
38690 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 69  utdown, if requi
386a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  red..**.** The x
386b0 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20  Create() method 
386c0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  is used to const
386d0 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 65  ruct a new cache
386e0 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a 2a   instance. The.*
386f0 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  * first paramete
38700 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74 68  r, szPage, is th
38710 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
38720 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 68 61  of the pages tha
38730 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 6c  t must.** be all
38740 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61  ocated by the ca
38750 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c 6c  che. szPage will
38760 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72 20   not be a power 
38770 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 73  of two. The.** s
38780 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
38790 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 74  bPurgeable, is t
387a0 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68 65  rue if the cache
387b0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 77   being created w
387c0 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 74  ill.** be used t
387d0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
387e0 20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f 6d   pages read from
387f0 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f   a file stored o
38800 6e 20 64 69 73 6b 2c