/ Hex Artifact Content
Login

Artifact 85c4398938ee2fd1382fee24bbedd5342a2bc2ed:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 35 30 20 32 30 30 39 2f 30  n,v 1.450 2009/0
05f0: 35 2f 31 34 20 32 32 3a 33 37 3a 34 38 20 64 72  5/14 22:37:48 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
4190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
41b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41c0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41d0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
41e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4200: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
4210: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4220: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
4230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4260: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4270: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
4280: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
42a0: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
42b0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
42c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
42d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
42e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42f0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4320: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4330: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
4340: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4350: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
4360: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
4370: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
4380: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4390: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
43a0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43b0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
43c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
43e0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43f0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
4400: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4410: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4420: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4430: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4460: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4470: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
4480: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4490: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
44a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
44b0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
44c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
44d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
44e0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
44f0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
4500: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
4510: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4520: 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ) */../*.** CAPI
4530: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4540: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4550: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4560: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4570: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4580: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4590: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
45a0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
45b0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
45c0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
45d0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
45e0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
45f0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
4600: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4610: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4620: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4630: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4640: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4650: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4660: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4680: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4690: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
46a0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
46b0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
46c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
46d0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
46e0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
46f0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4700: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4710: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4720: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4730: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4740: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4750: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4760: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4770: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4780: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4790: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
47a0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
47b0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
47c0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
47d0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
47e0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
47f0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4800: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4810: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4820: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4830: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4840: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4850: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4860: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4870: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4880: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4890: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
48a0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
48b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48c0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
48d0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
48e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48f0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
4900: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4910: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4920: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4930: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4950: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4960: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4980: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4990: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
49a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49b0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
49c0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
49d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49e0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
49f0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
4a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a10: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
4a20: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a40: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4a50: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4a70: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4a80: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4aa0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4ab0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4ac0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
4ad0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
4ae0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
4af0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
4b00: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
4b10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4b20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4b30: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4b40: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4b50: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4b60: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4b70: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4b80: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4b90: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4bb0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4bd0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4be0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4c00: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4c10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4c20: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4c40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4c50: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4c60: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4c70: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4c80: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4eb0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4ec0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4ed0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4ee0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4ef0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4f00: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4f20: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4f30: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4f40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4f50: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4f60: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4f70: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4f80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4f90: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4fa0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4fb0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4fc0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4fd0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4fe0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ff0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
5000: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
5010: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
5020: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
5030: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
5040: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
5050: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
5060: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
5070: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
5080: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5090: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
50a0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
50b0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
50c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
50d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
50e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
50f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
5100: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
5110: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
5120: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5140: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5150: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5160: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5170: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5180: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5190: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
51a0: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
51b0: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
51c0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
51d0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
51e0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
51f0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
5200: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5210: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
5220: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5230: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5240: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5250: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5260: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5270: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5280: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5290: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
52a0: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
52b0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
52c0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
52d0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
52e0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
52f0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
5300: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5310: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
5320: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5330: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5340: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5350: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5360: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5370: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5380: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5390: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
53a0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
53b0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
53c0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
53d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
53e0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
53f0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5400: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
5410: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
5420: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5430: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5440: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5450: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5460: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5470: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5480: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5490: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
54a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
54b0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
54c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
54d0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
54e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
54f0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5500: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5510: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5520: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5530: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5540: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5550: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5560: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5570: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5580: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5590: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
55a0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
55b0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
55c0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
55d0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
55e0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
55f0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
5600: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
5610: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
5620: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5630: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5640: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5650: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5660: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5670: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5680: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5690: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
56a0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
56b0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
56c0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
56d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
56e0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
56f0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
5700: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
5710: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
5720: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5730: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5740: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5750: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5760: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5770: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5780: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5790: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
57a0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
57b0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
57c0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
57d0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
57e0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
57f0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
5800: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
5810: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
5820: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5830: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5840: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5850: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5860: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5870: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5880: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5890: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
58a0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
58b0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
58c0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
58d0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
58e0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
58f0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
5900: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
5910: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
5920: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5930: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5940: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5950: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5960: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5970: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5980: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5990: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
59a0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
59b0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
59c0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
59d0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
59e0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
59f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
5a00: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
5a10: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
5a20: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5a30: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5a40: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5a50: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5a60: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5a70: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5a80: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5a90: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5aa0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5ab0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5ac0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
5ad0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
5ae0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
5af0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
5b00: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
5b10: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
5b20: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5b30: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5b40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b50: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5b70: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5b80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b90: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5ba0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bb0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5bc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bd0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5be0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5bf0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5c00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5c10: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c30: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5c50: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c70: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5c90: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5ca0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5cb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5cc0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5cd0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5ce0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5cf0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5d00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5d10: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5d20: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5d30: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5d40: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5d50: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5d60: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5d70: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5d80: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5d90: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5da0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5db0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5dc0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5dd0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5de0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5df0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5e00: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5e10: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5e20: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5e30: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5e40: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5e50: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5e60: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5e70: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5e80: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5e90: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5ea0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5eb0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5ec0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5ed0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5ee0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5ef0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5f00: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5f10: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5f20: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5f30: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5f40: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5f50: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5f60: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
5f70: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5f80: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
5f90: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5fa0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5fb0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5fc0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5fd0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5fe0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ff0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
6000: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6010: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
6020: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6030: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
6040: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
6050: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
6060: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
6070: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6080: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6090: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
60a0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
60b0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
60d0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
60e0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
60f0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6100: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6110: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
6120: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6130: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6140: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6150: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6160: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6170: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6180: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6190: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
61a0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
61b0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
61c0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
61d0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
61e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
61f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6200: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
6210: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6220: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6230: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6240: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6250: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6260: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6270: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6280: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6290: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
62a0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
62b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
62c0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
62d0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
62e0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
62f0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
6310: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
6320: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6330: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6340: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6350: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6360: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6370: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6380: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6390: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
63a0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
63b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
63c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
63d0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
63e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
63f0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
6400: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
6410: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
6420: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6430: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6440: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6450: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6460: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6470: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6480: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6490: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
64a0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
64b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
64c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
64d0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
64e0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
64f0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
6500: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
6510: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
6520: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6530: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6540: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6550: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6560: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6570: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6580: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6590: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
65a0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
65b0: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
65c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
65d0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
65e0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
65f0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
6600: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
6610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
6620: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6630: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6640: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6650: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6660: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6670: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6680: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6690: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
66a0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
66b0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
66c0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
66d0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
66e0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
66f0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
6700: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
6710: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
6720: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6730: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6740: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6750: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6760: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6770: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6780: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6790: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
67a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
67b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
67c0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
67d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
67e0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
67f0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
6800: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
6810: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
6820: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6830: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6840: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6850: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6860: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6870: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6880: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6890: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
68a0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
68b0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
68c0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
68d0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
68e0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
68f0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
6900: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
6910: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
6920: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6930: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6940: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6950: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6960: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6970: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6980: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6990: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
69a0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
69b0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
69c0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
69d0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
69e0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
69f0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6a00: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
6a10: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
6a20: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6a30: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6a40: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6a50: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6a60: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6a70: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6a80: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6a90: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6aa0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6ab0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6ac0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
6ad0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
6ae0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
6af0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
6b00: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
6b10: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
6b20: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6b30: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6b40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6b50: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6b60: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6b70: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6b80: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6b90: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6ba0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6bb0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6bc0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6bd0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6be0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6bf0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6c00: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6c10: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6c20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6c30: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6c40: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6c50: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6c60: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6c70: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6c80: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6c90: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6ca0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6cb0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6cc0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6cd0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6ce0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6cf0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6d00: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6d10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6d20: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6d30: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6d40: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6d50: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6d60: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6d70: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6d90: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6da0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6db0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6dc0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6dd0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6de0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6df0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6e00: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6e10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6e20: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6e30: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6e40: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6e50: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6e60: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6e70: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6e80: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6e90: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6ea0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6eb0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6ec0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6ed0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6ee0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6ef0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6f00: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6f10: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6f20: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6f30: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6f40: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6f50: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6f60: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6f70: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6f80: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6f90: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6fa0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6fb0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6fc0: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6fd0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6fe0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ff0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
7000: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
7010: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
7020: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
7030: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
7040: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
7050: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
7060: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
7070: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
7080: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7090: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
70a0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
70b0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
70c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
70d0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
70e0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
70f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7100: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7110: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
7120: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7130: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7140: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7150: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7170: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7180: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7190: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
71a0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
71b0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
71c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
71d0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
71e0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
71f0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
7200: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
7220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7240: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7250: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7260: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7270: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7280: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7290: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
72a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
72b0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
72c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
72d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
72e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
72f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7300: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7310: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
7320: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7340: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7350: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7360: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7370: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7380: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7390: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
73a0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
73b0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
73c0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
73d0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
73e0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
73f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
7400: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
7410: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
7420: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7430: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7440: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7450: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7460: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7470: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7480: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7490: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
74a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
74b0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
74c0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
74d0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
74e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
74f0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
7500: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
7510: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
7520: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7530: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7540: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7550: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7560: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7570: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7580: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7590: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
75a0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
75b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
75c0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
75d0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
75e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
75f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7600: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7610: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7620: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7630: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7640: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7650: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7660: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7670: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7680: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7690: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
76a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
76b0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
76c0: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
76d0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
76e0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
76f0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
7700: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
7710: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
7720: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
7730: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
7740: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
7750: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
7760: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
7770: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
7780: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
7790: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
77a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
77b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
77c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
77d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
77e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
77f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
7800: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
7810: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
7820: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
7830: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
7840: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
7850: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
7860: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
7870: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
7880: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
7890: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
78a0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
78b0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
78c0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
78d0: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
78e0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
78f0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
7900: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
7910: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
7920: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
7930: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
7940: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
7950: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7960: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
7970: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7980: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7990: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
79a0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
79b0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a  t fill it in..**
79c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
79d0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
79e0: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
79f0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
7a00: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
7a10: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
7a20: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
7a30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7a40: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
7a50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
7a60: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
7a70: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
7a80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
7a90: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
7aa0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
7ab0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
7ac0: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
7ad0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
7ae0: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ory..**.** SQLit
7af0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
7b00: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
7b10: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
7b20: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
7b30: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
7b40: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
7b50: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
7b60: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
7b70: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
7b80: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
7b90: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
7ba0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
7bb0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
7bc0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
7bd0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
7be0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
7bf0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
7c00: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
7c10: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
7c20: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
7c30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7c40: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
7c50: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
7c60: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
7c70: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
7c80: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
7c90: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
7ca0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
7cb0: 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43  xSleep(), and xC
7cc0: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74  urrentTime() int
7cd0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
7ce0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
7cf0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
7d00: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
7d10: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
7d20: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
7d30: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
7d40: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
7d50: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
7d60: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
7d70: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
7d80: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
7d90: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
7da0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
7db0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
7dc0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
7dd0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
7de0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
7df0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
7e00: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
7e10: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
7e20: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
7e30: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
7e40: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
7e50: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
7e60: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
7e70: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
7e80: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
7e90: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
7ea0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
7eb0: 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a  te and time..**.
7ec0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7ed0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
7ee0: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
7ef0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
7f00: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
7f10: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
7f20: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
7f30: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
7f40: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
7f50: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
7f60: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
7f70: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
7f80: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
7f90: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
7fa0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
7fb0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
7fc0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
7fd0: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
7fe0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8000: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
8010: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
8020: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
8030: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
8040: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
8050: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
8060: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
8070: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
8080: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8090: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
80a0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
80b0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
80c0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
80d0: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
80e0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
80f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8100: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8110: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
8120: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
8130: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8140: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8150: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
8160: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8170: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
8180: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8190: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
81a0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
81b0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
81c0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
81d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
81e0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
81f0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8200: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8210: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8220: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
8230: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
8240: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
8250: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
8260: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
8270: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
8290: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
82a0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
82b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
82c0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
82d0: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
82e0: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
82f0: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
8300: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
8310: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
8320: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
8330: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
8340: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
8350: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
8360: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
8370: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
8380: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
8390: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
83a0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
83b0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
83c0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
83d0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
83e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
83f0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
8400: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
8410: 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48  thod {H11190} <H
8420: 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11140>.**.** The
8430: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8440: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
8450: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
8460: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
8470: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8480: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
8490: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e  vfs] object. {EN
84a0: 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  D}  They determi
84b0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
84c0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
84d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
84e0: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
84f0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
8500: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
8510: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8520: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
8530: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8540: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
8550: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
8560: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
8570: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8580: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
8590: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  er the file is b
85a0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
85b0: 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69   writable..** Wi
85c0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
85d0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
85e0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
85f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8600: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8610: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8620: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8630: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8640: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8650: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8660: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8670: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8680: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
8690: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
86a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33  e Library {H1013
86b0: 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31  0} <S20000><S301
86c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
86d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
86e0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
86f0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
8700: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
8710: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
8720: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
8730: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
8740: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
8750: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
8760: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8770: 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20  lize()..**.** A 
8780: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8790: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
87a0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
87b0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
87c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
87d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
87e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
87f0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
8800: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
8810: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
8820: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
8830: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8840: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
8850: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
8860: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8870: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c  shutdown().  Onl
8880: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
8890: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
88a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
88b0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
88c0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
88d0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
88e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
88f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8900: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8910: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
8920: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
8930: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
8940: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
8950: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
8960: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
8970: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8980: 20 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66    Only.** an eff
8990: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
89a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
89b0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
89c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
89d0: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20  All other calls 
89e0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
89f0: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
8a00: 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  ss no-ops..**.**
8a10: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
8a20: 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  ngs, sqlite3_ini
8a30: 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20  tialize() shall 
8a40: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
8a50: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
8a60: 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33  milarly, sqlite3
8a70: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73  _shutdown().** s
8a80: 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  hall invoke sqli
8a90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
8aa0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
8ab0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
8ac0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
8ad0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
8ae0: 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73  ess..** If for s
8af0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
8b00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8b10: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
8b20: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
8b30: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
8b40: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
8b50: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
8b60: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
8b70: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
8b80: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
8b90: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
8ba0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
8bb0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ]..**.** The sql
8bc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8bd0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
8be0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
8bf0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
8c00: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
8c10: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
8c20: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
8c30: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
8c40: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
8c50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8c60: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
8c70: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
8c80: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
8c90: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
8ca0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
8cb0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
8cc0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
8cd0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
8ce0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
8cf0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
8d00: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
8d10: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
8d20: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
8d30: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
8d40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
8d50: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
8d60: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
8d70: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8d80: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
8d90: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
8da0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8db0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
8dc0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
8dd0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
8de0: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
8df0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
8e00: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
8e10: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
8e20: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
8e30: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
8e40: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
8e50: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
8e60: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
8e70: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
8e80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e90: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
8ea0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
8eb0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
8ec0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
8ed0: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
8ee0: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
8ef0: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
8f00: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
8f10: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
8f20: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
8f30: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
8f40: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
8f50: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
8f60: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
8f70: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
8f80: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
8f90: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
8fa0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
8fb0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
8fc0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
8fd0: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
8fe0: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
8ff0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
9000: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
9010: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9020: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
9030: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
9040: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9050: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
9060: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
9070: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
9080: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
9090: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
90a0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
90b0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
90c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
90d0: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
90e0: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
90f0: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
9100: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
9110: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
9120: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
9130: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
9140: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
9150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
9160: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
9170: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
9180: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
9190: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
91a0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
91b0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
91c0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
91d0: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
91e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
91f0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
9200: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
9210: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9220: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
9230: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
9240: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
9250: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
9260: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
9270: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
9280: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
9290: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
92a0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
92b0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
92c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
92d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
92e0: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
92f0: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
9300: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
9310: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
9320: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
9330: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
9340: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
9350: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
9360: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
9370: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
9380: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
9390: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
93a0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
93b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
93c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
93d0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
93e0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
93f0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
9400: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
9410: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
9420: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
9430: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
9440: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
9450: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
9460: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
9470: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
9480: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
9490: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
94a0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
94b0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
94c0: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
94d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
94e0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
94f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
9500: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9510: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
9520: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9530: 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30  y {H14100} <S200
9540: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45  00><S30200>.** E
9550: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
9560: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
9570: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
9580: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
9590: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
95a0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
95b0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
95c0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
95d0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
95e0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
95f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
9600: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
9610: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
9620: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
9630: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
9640: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
9650: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
9660: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
9670: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
9680: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
9690: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
96a0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
96b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
96c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
96d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
96e0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
96f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
9700: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
9710: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
9720: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
9730: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
9740: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
9750: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
9760: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
9770: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
9780: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
9790: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
97a0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
97b0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
97c0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
97d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
97e0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
97f0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
9800: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
9810: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
9820: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
9830: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
9840: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
9850: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
9860: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
9870: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
9880: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
9890: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
98a0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
98b0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
98c0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
98d0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
98e0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
98f0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
9900: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
9910: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
9920: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
9930: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
9940: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
9950: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
9960: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
9970: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
9980: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
9990: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
99a0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
99b0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
99c0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
99d0: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
99e0: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
99f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9a00: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a10: 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  _OK]..** If the 
9a20: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
9a30: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
9a40: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
9a50: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
9a60: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
9a70: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
9a80: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
9a90: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
9aa0: 3a 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48  :.** [H14103] [H
9ab0: 31 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20  14106] [H14120] 
9ac0: 5b 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36  [H14123] [H14126
9ad0: 5d 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31  ] [H14129] [H141
9ae0: 33 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20  32] [H14135].** 
9af0: 5b 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31  [H14138] [H14141
9b00: 5d 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31  ] [H14144] [H141
9b10: 34 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31  47] [H14150] [H1
9b20: 34 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b  4153] [H14156] [
9b30: 48 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31  H14159].** [H141
9b40: 36 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31  62] [H14165] [H1
9b50: 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  4168].*/.SQLITE_
9b60: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
9b70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
9b80: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
9b90: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
9ba0: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
9bb0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34  onnections  {H14
9bc0: 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  200} <S20000>.**
9bd0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
9be0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9bf0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
9c00: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
9c10: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
9c20: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
9c30: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
9c40: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
9c50: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
9c60: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
9c70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
9c80: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
9c90: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
9ca0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
9cb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
9cc0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
9cd0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
9ce0: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  t).  The.** sqli
9cf0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
9d00: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e  interface can on
9d10: 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64  ly be used immed
9d20: 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20  iately after.** 
9d30: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
9d40: 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  nection is creat
9d50: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
9d60: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  3_open()],.** [s
9d70: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
9d80: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  , or [sqlite3_op
9d90: 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  en_v2()].  .**.*
9da0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
9db0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
9dc0: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
9dd0: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63  ..)  is the.** c
9de0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
9df0: 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  b - an integer c
9e00: 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74  ode that indicat
9e10: 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63  es what.** aspec
9e20: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
9e30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
9e40: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
9e50: 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20  ed..** The only 
9e60: 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20  choice for this 
9e70: 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45  value is [SQLITE
9e80: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
9e90: 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72  IDE]..** New ver
9ea0: 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f  bs are likely to
9eb0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
9ec0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
9ed0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74  SQLite..** Addit
9ee0: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
9ef0: 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65  depend on the ve
9f00: 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  rb..**.** Requir
9f10: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32  ements:.** [H142
9f20: 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 5b 48 31  03] [H14206] [H1
9f30: 34 32 30 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b  4209] [H14212] [
9f40: 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54  H14215].*/.SQLIT
9f50: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
9f60: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
9f70: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
9f80: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
9f90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
9fa0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
9fb0: 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35  Routines {H10155
9fc0: 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58  } <S20120>.** EX
9fd0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
9fe0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
9ff0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
a000: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
a010: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
a020: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
a030: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
a040: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
a050: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
a060: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
a070: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
a080: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a090: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
a0a0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
a0b0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
a0c0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
a0d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
a0e0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
a0f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a100: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
a110: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
a120: 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20  ].  By creating 
a130: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a140: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
a150: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
a160: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a170: 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  )] during config
a180: 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61  uration, an.** a
a190: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
a1a0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
a1b0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  ative memory all
a1c0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
a1d0: 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20  m.** for SQLite 
a1e0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
a1f0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
a200: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
a210: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
a220: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20  te comes with a 
a230: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
a240: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69  allocator that i
a250: 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61  s.** perfectly a
a260: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
a270: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
a280: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
a290: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
a2a0: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
a2b0: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
a2c0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
a2d0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
a2e0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
a2f0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
a300: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
a310: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
a320: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
a330: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
a340: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
a350: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
a360: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
a370: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a380: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
a390: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
a3a0: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
a3b0: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
a3c0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
a3d0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
a3e0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
a3f0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
a400: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
a410: 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65  , xFree, and xRe
a420: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75  alloc methods mu
a430: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
a440: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72  .** malloc(), fr
a450: 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f  ee(), and reallo
a460: 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  c() functions fr
a470: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
a480: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78  library..**.** x
a490: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
a4a0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
a4b0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
a4c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
a4d0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
a4e0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
a4f0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
a500: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
a510: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
a520: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
a530: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
a540: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
a550: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
a560: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
a570: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
a580: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
a590: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
a5a0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
a5b0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
a5c0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
a5d0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
a5e0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
a5f0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
a600: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
a610: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
a620: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
a630: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
a640: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a650: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
a660: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
a670: 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54  er of 2..**.** T
a680: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
a690: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
a6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a6b0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
a6c0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
a6d0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
a6e0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
a6f0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
a700: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
a710: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
a720: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
a730: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
a740: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
a750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
a760: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
a770: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
a780: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
a790: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
a7a0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
a7b0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
a7c0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
a7d0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
a7e0: 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  tdown..*/.typede
a7f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
a800: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
a810: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
a820: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
a830: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
a840: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
a850: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
a860: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
a870: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
a880: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
a890: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
a8a0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
a8b0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
a8c0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
a8d0: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
a8e0: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
a8f0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
a900: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
a910: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
a920: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
a930: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
a940: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
a950: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
a960: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
a970: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
a980: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
a990: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
a9a0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
a9b0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
a9c0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
a9d0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
a9e0: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
a9f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
aa00: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
aa10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
aa20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
aa30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
aa40: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
aa50: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
aa60: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
aa70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
aa80: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
aa90: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30   Options {H10160
aaa0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
aab0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
aac0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
aad0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
aae0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
aaf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ab00: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ab10: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
ab20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ab30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ab40: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ab50: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
ab60: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ab70: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
ab80: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
ab90: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
aba0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
abb0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
abc0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
abd0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
abe0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
abf0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
ac00: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ac10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ac20: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
ac30: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
ac40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ac50: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ac60: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ac70: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ac80: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
ac90: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
aca0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
acb0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
acc0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
acd0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
ace0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
acf0: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
ad00: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
ad10: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
ad20: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
ad30: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73   This option dis
ad40: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
ad50: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
ad60: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
ad70: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
ad80: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
ad90: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
ada0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
adb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
adc0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
add0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ade0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
adf0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ae00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
ae10: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
ae20: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
ae30: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
ae40: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ae50: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
ae60: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
ae70: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
ae80: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
ae90: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
aea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
aeb0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
aec0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
aed0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
aee0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
aef0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
af00: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
af10: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
af20: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
af30: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
af40: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
af50: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
af60: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
af70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
af80: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
af90: 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  .  See the [thre
afa0: 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64  ading mode].** d
afb0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
afc0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
afd0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  rmation.</dd>.**
afe0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
aff0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
b000: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
b010: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
b020: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
b030: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
b040: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
b050: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
b060: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
b070: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
b080: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b090: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
b0a0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
b0b0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
b0c0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
b0d0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
b0e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b0f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
b100: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
b110: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
b120: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
b130: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
b140: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
b150: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
b160: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
b170: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
b180: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
b190: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
b1a0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
b1b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b1c0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
b1d0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
b1e0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
b1f0: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
b200: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
b210: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
b220: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
b230: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
b240: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
b250: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
b260: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b270: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
b280: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b290: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
b2a0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
b2b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b2c0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
b2d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
b2e0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
b2f0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
b300: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
b310: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
b320: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
b330: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b340: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
b350: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
b360: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b370: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
b380: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
b390: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b3a0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b3b0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
b3c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
b3d0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
b3e0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
b3f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
b400: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
b410: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
b420: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
b430: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
b440: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
b450: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
b460: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
b470: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
b480: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b490: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
b4a0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
b4b0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
b4c0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
b4d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
b4e0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
b4f0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
b500: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
b510: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
b520: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
b530: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
b540: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
b550: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b560: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b570: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
b580: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
b590: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
b5a0: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
b5b0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
b5c0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
b5d0: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
b5e0: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
b5f0: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
b600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
b610: 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20  tatistics. When 
b620: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
b630: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
b640: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
b650: 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69   .** non-operati
b660: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
b670: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
b680: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
b690: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b6a0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
b6b0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
b6c0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
b6d0: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
b6e0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b6f0: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
b700: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a   </ul>.** </dd>.
b710: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b720: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
b730: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b740: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b750: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b760: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b770: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b780: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
b790: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
b7a0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
b7b0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
b7c0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a  e memory, the.**
b7d0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
b7e0: 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a  ratch buffer (sz
b7f0: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
b800: 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29  r of buffers (N)
b810: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
b820: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
b830: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
b840: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
b850: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
b860: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
b870: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
b880: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
b890: 65 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65  equired due inte
b8a0: 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a  rnal overhead..*
b8b0: 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61  * The first.** a
b8c0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b8d0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
b8e0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
b8f0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
b900: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
b910: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
b920: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
b930: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e  tch buffer at on
b940: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73  ce per thread, s
b950: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
b960: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65   set to the expe
b970: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
b980: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20  ber of threads. 
b990: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d   The sz.** param
b9a0: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36  eter should be 6
b9b0: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20   times the size 
b9c0: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
b9d0: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
b9e0: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75  e..** Scratch bu
b9f0: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61  ffers are used a
ba00: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74  s part of the bt
ba10: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72  ree balance oper
ba20: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68  ation.  If.** Th
ba30: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72  e btree balancer
ba40: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
ba50: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  l memory beyond 
ba60: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ba70: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62   by.** scratch b
ba80: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20  uffers or if no 
ba90: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73  scratch buffer s
baa0: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65  pace is specifie
bab0: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  d, then SQLite.*
bac0: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  * goes to [sqlit
bad0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20  e3_malloc()] to 
bae0: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
baf0: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e  y it needs.</dd>
bb00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bb10: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
bb20: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
bb30: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bb40: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bb50: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bb60: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
bb70: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
bb80: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
bb90: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
bba0: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
bbb0: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
bbc0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
bbd0: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
bbe0: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
bbf0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
bc00: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
bc10: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
bc20: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
bc30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
bc40: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
bc50: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
bc60: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bc70: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
bc80: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d  er to the.** mem
bc90: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
bca0: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
bcb0: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
bcc0: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
bcd0: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
bce0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
bcf0: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
bd00: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
bd10: 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74  2768.  The first
bd20: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
bd30: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
bd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
bd50: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
bd60: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
bd70: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
bd80: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
bd90: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
bda0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
bdb0: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
bdc0: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
bdd0: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
bde0: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
bdf0: 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69  ache.  If additi
be00: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
be10: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
be20: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
be30: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
be40: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
be50: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
be60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
be70: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
be80: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
be90: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69   space..** The i
bea0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
beb0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
bec0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
bed0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
bee0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
bef0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
bf00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bf10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
bf20: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AP</dt>.** <dd>T
bf30: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bf40: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bf50: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bf60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
bf70: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
bf80: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
bf90: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
bfa0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
bfb0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
bfc0: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
bfd0: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
bfe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bff0: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
c000: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c010: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
c020: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
c030: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
c040: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  * bytes in the m
c050: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
c060: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
c070: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20  location size.  
c080: 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  If.** the first 
c090: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
c0a0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
c0b0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
c0c0: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
c0d0: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
c0e0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c0f0: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
c100: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
c110: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
c120: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
c130: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
c140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
c150: 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d  C].  If the.** m
c160: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
c170: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
c180: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
c190: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
c1a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
c1b0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
c1c0: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
c1d0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
c1e0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
c1f0: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
c200: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
c210: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
c220: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64  cation needs.</d
c230: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c240: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c250: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c260: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
c270: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c280: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
c290: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
c2a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
c2b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c2c0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c2d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
c2e0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
c2f0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
c300: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
c310: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c320: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
c330: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
c340: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
c350: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c360: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
c370: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  EX</dt>.** <dd>T
c380: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c390: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c3a0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c3b0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
c3c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
c3d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c3e0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
c3f0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
c400: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
c410: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
c420: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
c430: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
c440: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
c450: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  es..** This opti
c460: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
c470: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
c480: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
c490: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
c4a0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
c4b0: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
c4c0: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
c4d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
c4e0: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
c4f0: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
c500: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
c510: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c520: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
c530: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c540: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
c550: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
c560: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
c570: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61  .** memory allca
c580: 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f  tion lookaside o
c590: 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68  ptimization.  Th
c5a0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c5b0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
c5c0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
c5d0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
c5e0: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
c5f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
c600: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
c610: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
c620: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64  e connection.</d
c630: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c640: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
c650: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c660: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c670: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c680: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c690: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
c6a0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
c6b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
c6c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
c6d0: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
c6e0: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
c6f0: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
c700: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53  plementation.  S
c710: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
c720: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
c730: 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
c740: 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
c750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c760: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c770: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c780: 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  GETPCACHE</dt>.*
c790: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c7a0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c7b0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c7c0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c7d0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
c7e0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
c7f0: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
c800: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
c810: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
c820: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c830: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
c840: 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ct.</dd>.**.** <
c850: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
c860: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c870: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
c880: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
c890: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
c8a0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
c8b0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c8c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c8d0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
c8e0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
c8f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c900: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
c910: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
c920: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c940: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
c950: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
c960: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
c970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c980: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
c990: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
c9a0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
c9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c9c0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c9d0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
c9e0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
c9f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ca00: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
ca10: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
ca20: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
ca30: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
ca40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ca50: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
ca60: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
ca70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ca80: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
ca90: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
caa0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
cab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cac0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
cad0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
cae0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
caf0: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
cb00: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
cb10: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
cb20: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
cb30: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
cb40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cb50: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
cb60: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
cb70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cb80: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
cb90: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
cba0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
cbb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cbc0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
cbd0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
cbe0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
cbf0: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  hods* */../*.** 
cc00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
cc10: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  uration Options 
cc20: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30  {H10170} <S20000
cc30: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
cc40: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  L.**.** These co
cc50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
cc60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
cc70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
cc80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
cc90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
cca0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ccb0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ccc0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
ccd0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
cce0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
ccf0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
cd00: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
cd10: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
cd20: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
cd30: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
cd40: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
cd50: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
cd60: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
cd70: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
cd80: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
cd90: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
cda0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
cdb0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
cdc0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
cdd0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
cde0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
cdf0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
ce00: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
ce10: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
ce20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
ce30: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
ce40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ce50: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
ce60: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
ce70: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
ce80: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
ce90: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
cea0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
ceb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
cec0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
ced0: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
cee0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
cef0: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
cf00: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
cf10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cf20: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
cf30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
cf40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
cf50: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
cf60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
cf70: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
cf80: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
cf90: 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
cfa0: 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20  de memory.  The 
cfb0: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
cfc0: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  t may be NULL in
cfd0: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
cfe0: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
cff0: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
d000: 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  * buffer itself 
d010: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d020: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73  alloc()].  The s
d030: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
d040: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
d050: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
d060: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
d070: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
d080: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
d090: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
d0a0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
d0b0: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
d0c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
d0d0: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
d0e0: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
d0f0: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
d100: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
d110: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f  ird arguments.</
d120: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d140: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
d150: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
d160: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
d170: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
d180: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
d190: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
d1a0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
d1b0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
d1c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d1d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d1e0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
d1f0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
d200: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
d210: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d220: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
d230: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
d240: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
d250: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
d260: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
d270: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
d280: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d290: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
d2a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
d2b0: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
d2c0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
d2d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d2e0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
d2f0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
d300: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
d310: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
d320: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
d330: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
d340: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
d350: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
d360: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
d370: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
d380: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
d390: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
d3a0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
d3b0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
d3c0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
d3d0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
d3e0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
d3f0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
d400: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
d410: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
d420: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
d430: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
d440: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
d450: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
d460: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
d470: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
d480: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
d490: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
d4a0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
d4b0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
d4c0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
d4d0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
d4e0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
d4f0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
d500: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
d510: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
d520: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
d530: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
d540: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
d550: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
d560: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
d570: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
d580: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
d590: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
d5a0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
d5b0: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
d5c0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
d5d0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
d5e0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
d5f0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
d600: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
d610: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
d620: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
d630: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
d640: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
d650: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
d660: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
d670: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
d680: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
d690: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
d6a0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
d6b0: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
d6c0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
d6d0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
d6e0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
d6f0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
d700: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
d710: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
d720: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
d730: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
d740: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d750: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
d760: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
d770: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
d780: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
d790: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
d7a0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
d7b0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
d7c0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
d7d0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
d7e0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
d7f0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
d800: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
d810: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
d820: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
d830: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
d840: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
d850: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
d860: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
d870: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
d880: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
d890: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
d8a0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
d8b0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
d8c0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
d8d0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
d8e0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
d8f0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
d900: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
d910: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
d920: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
d930: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
d940: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
d950: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
d960: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
d970: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
d980: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
d990: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
d9a0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
d9b0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
d9c0: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
d9d0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
d9e0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
d9f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
da00: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
da10: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
da20: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
da30: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
da40: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
da50: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
da60: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
da70: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
da80: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
da90: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
daa0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
dab0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
dac0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
dad0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
dae0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
daf0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
db00: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
db10: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
db20: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
db30: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
db40: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
db50: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
db60: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
db70: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
db80: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
db90: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
dba0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
dbb0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
dbc0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
dbd0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
dbe0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
dbf0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
dc00: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
dc10: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
dc20: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
dc30: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
dc40: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
dc50: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
dc60: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
dc70: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
dc80: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
dc90: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
dca0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
dcb0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
dcc0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
dcd0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
dce0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
dcf0: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
dd00: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
dd10: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
dd20: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
dd30: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
dd40: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
dd50: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
dd60: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
dd70: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
dd80: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
dd90: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
dda0: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
ddb0: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
ddc0: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
ddd0: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
dde0: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
ddf0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
de00: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
de10: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
de20: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
de30: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
de40: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
de50: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
de60: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
de70: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
de80: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
de90: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
dea0: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
deb0: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
dec0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
ded0: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
dee0: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
def0: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
df00: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
df10: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
df20: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
df30: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
df40: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
df50: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
df60: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
df70: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
df80: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
df90: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
dfa0: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
dfb0: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
dfc0: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
dfd0: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
dfe0: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
dff0: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
e000: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
e010: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
e020: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
e030: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
e040: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
e050: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
e060: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
e070: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
e080: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
e090: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
e0a0: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
e0b0: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
e0c0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
e0d0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
e0e0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
e0f0: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
e100: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
e110: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
e120: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
e130: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
e140: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
e150: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
e160: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
e170: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e180: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e190: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
e1a0: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
e1b0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
e1c0: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
e1d0: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
e1e0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
e1f0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
e200: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
e210: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
e220: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
e230: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
e240: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
e250: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
e260: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
e270: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
e280: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
e290: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
e2a0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
e2b0: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
e2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
e2d0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
e2e0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
e2f0: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
e300: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e310: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
e320: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
e330: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
e340: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
e350: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
e360: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
e370: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
e380: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
e390: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
e3a0: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
e3b0: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
e3c0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
e3d0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e3e0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
e3f0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
e400: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
e410: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
e420: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34  ments:.** [H1224
e430: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a  1] [H12243].**.*
e440: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
e450: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
e460: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
e470: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e480: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
e490: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e4a0: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
e4b0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
e4c0: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
e4d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
e4e0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
e4f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
e500: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
e510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e520: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
e530: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
e540: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
e550: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
e560: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
e570: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
e580: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e590: 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
e5a0: 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
e5b0: 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
e5c0: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
e5d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
e5e0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
e5f0: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
e600: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
e610: 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20  all .** [CREATE 
e620: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
e630: 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  r] contexts.  Ho
e640: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
e650: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
e660: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
e670: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
e680: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
e690: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
e6a0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e6b0: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
e6c0: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
e6d0: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
e6e0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 72 6f  ount does not ro
e6f0: 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
e700: 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
e710: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 20 74  D OF trigger], t
e720: 68 6f 75 67 68 20 69 66 0a 2a 2a 20 74 68 65 20  hough if.** the 
e730: 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
e740: 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
e750: 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
e760: 73 65 20 63 68 61 6e 67 65 73 20 61 72 65 0a 2a  se changes are.*
e770: 2a 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68  * counted..** Th
e780: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
e790: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
e7a0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
e7b0: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
e7c0: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28  s.** completed (
e7d0: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
e7e0: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
e7f0: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
e800: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
e810: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
e820: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
e830: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
e840: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
e850: 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a  erface and the.*
e860: 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
e870: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20   pragma]..**.** 
e880: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
e890: 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36   [H12261] [H1226
e8a0: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
e8b0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
e8c0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
e8d0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
e8e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
e8f0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
e900: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
e910: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
e920: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
e930: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
e940: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
e950: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
e960: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
e970: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
e980: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e990: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
e9a0: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
e9b0: 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35  y {H12270} <S305
e9c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
e9d0: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
e9e0: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
e9f0: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
ea00: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
ea10: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
ea20: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
ea30: 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
ea40: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
ea50: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
ea60: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
ea70: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
ea80: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
ea90: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
eaa0: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
eab0: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
eac0: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
ead0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
eae0: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
eaf0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
eb00: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
eb10: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
eb20: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
eb30: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
eb40: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
eb50: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
eb60: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
eb70: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
eb80: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
eb90: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
eba0: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
ebb0: 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
ebc0: 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
ebd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
ebe0: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
ebf0: 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
ec00: 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
ec10: 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
ec20: 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
ec30: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
ec40: 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
ec50: 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
ec60: 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
ec70: 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
ec80: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
ec90: 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
eca0: 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
ecb0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
ecc0: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
ecd0: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
ece0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ecf0: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
ed00: 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
ed10: 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
ed20: 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
ed30: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
ed40: 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
ed50: 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
ed60: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
ed70: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
ed80: 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
ed90: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
eda0: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
edb0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
edc0: 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
edd0: 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
ede0: 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
edf0: 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
ee00: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
ee10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ee20: 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
ee30: 20 20 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74    Any new SQL st
ee40: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
ee50: 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
ee60: 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
ee70: 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
ee80: 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
ee90: 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
eea0: 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
eeb0: 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
eec0: 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
eed0: 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
eee0: 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
eef0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ef00: 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51  () call.  New SQ
ef10: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
ef20: 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
ef30: 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
ef40: 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
ef50: 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
ef60: 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
ef70: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
ef80: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
ef90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
efa0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
efb0: 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
efc0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
efd0: 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
efe0: 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
eff0: 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
f000: 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
f010: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
f020: 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
f030: 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
f040: 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
f050: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52  returns..**.** R
f060: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
f070: 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32  [H12271] [H12272
f080: 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ].**.** If the d
f090: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f0a0: 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
f0b0: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
f0c0: 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
f0d0: 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
f0e0: 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
f0f0: 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
f100: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f110: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
f120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
f130: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
f140: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
f150: 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d  omplete {H10510}
f160: 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70200>.**.** 
f170: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
f180: 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
f190: 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
f1a0: 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
f1b0: 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
f1c0: 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
f1d0: 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
f1e0: 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
f1f0: 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
f200: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
f210: 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
f220: 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
f230: 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
f240: 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
f250: 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
f260: 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
f270: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
f280: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
f290: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
f2a0: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
f2b0: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
f2c0: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
f2d0: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
f2e0: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
f2f0: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
f300: 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
f310: 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
f320: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
f330: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
f340: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
f350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
f360: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
f370: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
f380: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
f390: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
f3a0: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
f3b0: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
f3c0: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
f3d0: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
f3e0: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
f3f0: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
f400: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
f410: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
f420: 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
f430: 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
f440: 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
f450: 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
f460: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  gnored..**.** Th
f470: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
f480: 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
f490: 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
f4a0: 6c 65 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d  lete.  If a.** m
f4b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f4c0: 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
f4d0: 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
f4e0: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
f4f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
f500: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
f510: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
f520: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
f530: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
f540: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
f550: 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
f560: 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
f570: 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
f580: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
f590: 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
f5a0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
f5b0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
f5c0: 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
f5d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f5e0: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
f5f0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
f600: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
f610: 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
f620: 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
f630: 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
f640: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
f650: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
f660: 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
f670: 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
f680: 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
f690: 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
f6a0: 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a  L is complete..*
f6b0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
f6c0: 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30  s: [H10511] [H10
f6d0: 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  512].**.** The i
f6e0: 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
f6f0: 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
f700: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
f710: 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
f720: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
f730: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
f740: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
f750: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
f760: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
f770: 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
f780: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
f790: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
f7a0: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
f7b0: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
f7c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f7d0: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
f7e0: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
f7f0: 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
f800: 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
f810: 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
f820: 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d   Errors {H12310}
f830: 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40400>.**.** 
f840: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
f850: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
f860: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
f870: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
f880: 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
f890: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
f8a0: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
f8b0: 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
f8c0: 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
f8d0: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
f8e0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62  ..**.** If the b
f8f0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
f900: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
f910: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
f920: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
f930: 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
f940: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
f950: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
f960: 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65  the lock. If the
f970: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
f980: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
f990: 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
f9a0: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
f9b0: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
f9c0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nts..**.** The f
f9d0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f9e0: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
f9f0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
fa00: 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
fa10: 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
fa20: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
fa30: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
fa40: 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  er().  The secon
fa50: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
fa60: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c   the handler cal
fa70: 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
fa80: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
fa90: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
faa0: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
fab0: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
fac0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
fad0: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
fae0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
faf0: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
fb00: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
fb10: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
fb20: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
fb30: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
fb40: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
fb50: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
fb60: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
fb70: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
fb80: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
fb90: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
fba0: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
fbb0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
fbc0: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
fbd0: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
fbe0: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
fbf0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
fc00: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
fc10: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
fc20: 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
fc30: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
fc40: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
fc50: 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c  ntention. If SQL
fc60: 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
fc70: 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
fc80: 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
fc90: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
fca0: 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
fcb0: 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
fcc0: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
fcd0: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
fce0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
fcf0: 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
fd00: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
fd10: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
fd20: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
fd30: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
fd40: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
fd50: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
fd60: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
fd70: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
fd80: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
fd90: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
fda0: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
fdb0: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
fdc0: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
fdd0: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
fde0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
fdf0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
fe00: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
fe10: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
fe20: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
fe30: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
fe40: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
fe50: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
fe60: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
fe70: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
fe80: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
fe90: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
fea0: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
feb0: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
fec0: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
fed0: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
fee0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
fef0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
ff00: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
ff10: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
ff20: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
ff30: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
ff40: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
ff50: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
ff60: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
ff70: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
ff80: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
ff90: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
ffa0: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
ffb0: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
ffc0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
ffd0: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
ffe0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
fff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10000 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
10010 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
10020 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
10030 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
10040 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
10050 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
10060 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
10070 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
10080 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
10090 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
100a0 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
100b0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
100c0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
100d0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
100e0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
100f0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
10100 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
10110 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
10120 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
10130 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
10140 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
10150 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
10160 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
10170 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
10180 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
10190 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
101a0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
101b0 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
101c0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
101d0 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
101e0 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
101f0 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
10200 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
10210 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
10220 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10230 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
10240 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
10250 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
10260 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
10270 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
10280 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
10290 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
102a0 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
102b0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
102c0 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
102d0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
102e0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
102f0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
10300 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
10310 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
10320 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
10330 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
10340 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
10350 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
10360 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10370 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
10380 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
10390 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
103a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
103b0 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74  et handler.  Not
103c0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
103d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
103e0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
103f0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
10400 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
10410 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
10420 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
10430 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
10440 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
10450 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
10460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
10470 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
10480 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
10490 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
104a0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
104b0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
104c0 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65  ..** .** Require
104d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31  ments:.** [H1231
104e0 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32  1] [H12312] [H12
104f0 33 31 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48  314] [H12316] [H
10500 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62  12318].**.** A b
10510 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
10520 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
10530 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10540 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
10550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
10560 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
10570 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
10580 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
10590 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
105a0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
105b0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
105c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
105d0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
105e0 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
105f0 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
10600 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
10610 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10620 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
10630 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
10640 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
10650 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
10660 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
10670 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
10680 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
10690 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
106a0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
106b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
106c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
106d0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
106e0 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
106f0 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
10700 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
10710 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
10720 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
10730 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
10740 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
10750 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
10760 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10770 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
10780 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
10790 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
107a0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
107b0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
107c0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
107d0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
107e0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
107f0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
10800 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
10810 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
10820 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
10830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10840 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
10850 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
10860 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
10870 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
10880 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
10890 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
108a0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
108b0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
108c0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
108d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
108e0 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ared..**.** Requ
108f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
10900 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b  2341] [H12343] [
10910 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12344].*/.int s
10920 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
10930 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
10940 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
10950 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
10960 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
10970 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
10980 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
10990 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
109a0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
109b0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
109c0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
109d0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
109e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
109f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
10a00 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
10a10 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
10a20 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
10a30 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
10a40 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
10a50 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
10a60 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
10a70 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
10a80 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
10a90 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
10aa0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
10ab0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
10ac0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
10ad0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
10ae0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
10af0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
10b00 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
10b10 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
10b20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
10b30 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
10b40 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
10b50 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
10b60 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
10b70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10b80 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
10b90 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
10ba0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
10bb0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
10bc0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
10bd0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
10be0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
10bf0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
10c00 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
10c10 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
10c20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
10c30 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
10c40 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
10c50 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
10c60 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
10c70 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
10c80 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
10c90 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
10ca0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
10cb0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
10cc0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
10cd0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
10ce0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
10cf0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
10d00 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
10d10 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
10d20 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
10d30 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
10d40 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
10d50 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
10d60 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
10d70 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
10d80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10d90 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
10da0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
10db0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
10dc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
10dd0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
10de0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
10df0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
10e00 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
10e10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
10e20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
10e30 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
10e40 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
10e50 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
10e60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10e70 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
10e80 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
10e90 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
10ea0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
10eb0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
10ec0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
10ed0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
10ee0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
10ef0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
10f00 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
10f10 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
10f20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
10f30 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
10f40 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
10f50 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
10f60 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
10f70 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
10f80 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
10f90 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
10fa0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
10fb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
10fc0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10fd0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
10fe0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10ff0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
11000 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11010 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
11020 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
11030 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
11040 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
11050 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11060 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
11070 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11080 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
11090 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
110a0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
110b0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
110c0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
110d0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
110e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
110f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
11100 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
11110 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
11120 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
11130 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
11140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
11150 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
11160 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
11170 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
11180 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
11190 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
111a0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
111b0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
111c0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
111d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
111e0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
111f0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
11200 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
11210 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
11220 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
11230 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
11240 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
11250 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
11260 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
11270 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
11280 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
11290 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
112a0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
112b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
112c0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
112d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
112e0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
112f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
11300 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
11310 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
11320 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
11330 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
11340 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
11350 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
11360 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
11370 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
11380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11390 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
113a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
113b0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
113c0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
113d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
113e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
113f0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
11400 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
11410 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
11420 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
11430 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
11440 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
11450 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
11460 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
11470 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
11480 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
11490 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
114a0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
114b0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
114c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
114d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
114e0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
114f0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
11500 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
11510 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
11520 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
11530 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
11540 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
11550 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33  * [H12371] [H123
11560 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31  73] [H12374] [H1
11570 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b  2376] [H12379] [
11580 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12382].*/.int s
11590 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
115a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
115b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
115c0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
115d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
115e0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
115f0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
11600 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
11610 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
11620 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
11630 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
11640 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
11650 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
11660 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
11670 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
11680 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
11690 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
116a0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
116b0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
116c0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
116d0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
116e0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
116f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
11700 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
11710 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
11720 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
11730 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
11740 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
11750 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30  {H17400} <S70000
11760 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20000>.**.** 
11770 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11780 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
11790 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
117a0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
117b0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
117c0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
117d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
117e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
117f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
11800 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
11810 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
11820 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
11830 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
11840 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11850 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
11860 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
11870 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
11880 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
11890 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
118a0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42  ite3_free()].  B
118b0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
118c0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
118d0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
118e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
118f0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11900 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
11910 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
11920 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
11930 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
11940 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
11950 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
11960 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
11970 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
11980 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
11990 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
119a0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
119b0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
119c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
119d0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
119e0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
119f0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
11a00 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
11a10 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
11a20 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
11a30 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
11a40 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
11a50 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
11a60 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
11a70 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
11a80 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
11a90 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
11aa0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
11ab0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
11ac0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
11ad0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11ae0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
11af0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
11b00 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
11b10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
11b20 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
11b30 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
11b40 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
11b50 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
11b60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
11b70 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
11b80 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
11b90 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
11ba0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
11bb0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
11bc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11bd0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
11be0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
11bf0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
11c00 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
11c10 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
11c20 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
11c30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
11c40 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
11c50 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
11c60 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
11c70 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
11c80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
11c90 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
11ca0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
11cb0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
11cc0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
11cd0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
11ce0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
11cf0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
11d00 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
11d10 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
11d20 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
11d30 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
11d40 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
11d50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11d60 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
11d70 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
11d80 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
11d90 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
11da0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
11db0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
11dc0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
11dd0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
11de0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
11df0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
11e00 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
11e10 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
11e20 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
11e30 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11e40 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
11e50 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
11e60 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
11e70 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
11e80 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
11e90 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
11ea0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
11eb0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
11ec0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
11ed0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
11ee0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
11ef0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
11f00 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
11f10 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
11f20 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
11f30 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
11f40 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
11f50 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
11f60 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
11f70 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
11f80 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
11f90 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
11fa0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
11fb0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
11fc0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
11fd0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
11fe0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
11ff0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
12000 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
12010 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
12020 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
12030 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
12040 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
12050 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12060 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
12070 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
12080 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
12090 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
120a0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
120b0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
120c0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
120d0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
120e0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
120f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12100 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
12110 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
12120 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
12130 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
12140 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
12150 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
12160 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
12170 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
12180 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12190 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
121a0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
121b0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
121c0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
121d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
121e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
121f0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
12200 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
12210 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
12220 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
12230 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
12240 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
12250 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12260 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
12270 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
12280 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
12290 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
122a0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
122b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
122c0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
122d0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
122e0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
122f0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
12300 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
12310 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
12320 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
12330 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
12340 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
12350 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77   The %Q option w
12360 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
12370 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
12380 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
12390 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
123a0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
123b0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
123c0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
123d0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
123e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
123f0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
12400 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
12410 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
12420 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
12430 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69  single quotes) i
12440 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
12450 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66  Q option.  So, f
12460 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
12470 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
12480 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12490 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
124a0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
124b0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
124c0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
124d0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
124e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
124f0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
12500 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
12510 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
12520 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12530 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
12540 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
12550 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
12560 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
12570 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
12580 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
12590 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
125a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
125b0 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f  *.** The "%z" fo
125c0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
125d0 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69  works exactly li
125e0 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65  ke "%s" with the
125f0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
12600 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
12610 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
12620 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
12630 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
12640 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12650 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
12660 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20  e input string. 
12670 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75  {END}.**.** Requ
12680 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
12690 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b  7403] [H17406] [
126a0 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20  H17407].*/.char 
126b0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
126c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
126d0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
126e0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
126f0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
12700 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
12710 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
12720 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
12730 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12740 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12750 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
12760 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30  m {H17300} <S200
12770 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00>.**.** The SQ
12780 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20  Lite core  uses 
12790 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
127a0 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
127b0 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
127c0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
127d0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
127e0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
127f0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
12800 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
12810 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
12820 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
12830 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
12840 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
12850 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
12860 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
12870 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
12880 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ations..**.** Th
12890 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
128a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
128b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
128c0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
128d0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
128e0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
128f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
12900 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66  parameter..** If
12910 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
12920 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
12930 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
12940 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
12950 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
12960 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
12970 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
12980 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
12990 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
129a0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
129b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
129d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
129e0 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  * Calling sqlite
129f0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
12a00 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
12a10 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
12a20 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
12a30 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
12a40 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
12a50 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
12a60 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
12a70 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65   be reused.  The
12a80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
12a90 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
12aa0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
12ab0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
12ac0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
12ad0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
12ae0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
12af0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
12b00 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
12b10 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
12b20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
12b30 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
12b40 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
12b50 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
12b60 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
12b70 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
12b80 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
12b90 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
12ba0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
12bb0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
12bc0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
12bd0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
12be0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
12bf0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
12c00 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
12c10 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
12c20 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
12c30 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
12c40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
12c50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
12c60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12c70 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
12c80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
12c90 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
12ca0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
12cb0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
12cc0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
12cd0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
12ce0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
12cf0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
12d00 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
12d10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12d20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
12d30 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
12d40 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69  eter.  If the fi
12d50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
12d60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12d70 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
12d80 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
12d90 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
12da0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
12db0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
12dc0 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
12dd0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
12de0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
12df0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
12e00 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
12e10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
12e20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
12e30 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
12e40 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
12e50 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
12e60 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
12e70 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
12e80 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
12e90 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
12ea0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
12eb0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
12ec0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12ed0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
12ee0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
12ef0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
12f00 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
12f10 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
12f20 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
12f30 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
12f40 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69  lable..** If M i
12f50 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
12f60 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
12f70 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
12f80 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
12f90 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
12fa0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
12fb0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
12fc0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
12fd0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
12fe0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
12ff0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
13000 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
13010 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61  * If sqlite3_rea
13020 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
13030 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
13040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
13050 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
13060 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
13070 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
13080 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
13090 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
130a0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
130b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
130c0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
130d0 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a  oundary. {END}.*
130e0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
130f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13100 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  of the memory al
13110 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
13120 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d  em uses.** the m
13130 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
13140 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72  () and free() pr
13150 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74  ovided by the st
13160 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13170 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f  ..** {H17382} Ho
13180 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
13190 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
131a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
131b0 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e  MEMORY_SIZE=<i>N
131c0 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63  NN</i> C preproc
131d0 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65  essor macro (whe
131e0 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a  re <i>NNN</i>.**
131f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c   is an integer),
13200 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65   then SQLite cre
13210 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72  ate a static arr
13220 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a  ay of at least.*
13230 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74  * <i>NNN</i> byt
13240 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75  es in size and u
13250 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66  ses that array f
13260 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
13270 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20  namic.** memory 
13280 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
13290 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f  . {END}  Additio
132a0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
132b0 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20  ator options.** 
132c0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
132d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
132e0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
132f0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
13300 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
13310 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
13320 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
13330 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
13340 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
13350 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
13360 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
13370 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
13380 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
13390 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
133a0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
133b0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
133c0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
133d0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
133e0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
133f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69  ed..**.** The Wi
13400 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
13410 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
13420 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
13430 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
13440 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
13450 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
13460 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
13470 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
13480 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
13490 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
134a0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
134b0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
134c0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
134d0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
134e0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
134f0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
13500 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
13510 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
13520 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
13530 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
13540 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
13550 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
13560 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
13570 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
13580 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33  ents:.** [H17303
13590 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 37 33  ] [H17304] [H173
135a0 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48 31  05] [H17306] [H1
135b0 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b  7310] [H17312] [
135c0 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 38 5d  H17315] [H17318]
135d0 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48 31  .** [H17321] [H1
135e0 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a  7322] [H17323].*
135f0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
13600 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
13610 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
13620 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
13630 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
13640 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
13650 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
13660 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
13670 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
13680 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
13690 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
136a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
136b0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
136c0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
136d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
136e0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
136f0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
13700 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
13710 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
13720 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
13730 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
13740 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
13750 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
13760 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
13770 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
13780 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
13790 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
137a0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
137b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
137c0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
137d0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
137e0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
137f0 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
13800 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
13810 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
13820 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
13830 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
13840 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
13850 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
13860 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
13870 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
13880 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
13890 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
138a0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
138b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
138c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
138d0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
138e0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
138f0 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 37 33 37   [H17371] [H1737
13900 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 48 31 37  3] [H17374] [H17
13910 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  375].*/.sqlite3_
13920 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
13930 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
13940 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
13950 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
13960 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
13970 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
13980 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
13990 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
139a0 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d  nerator {H17390}
139b0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
139c0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
139d0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
139e0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
139f0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
13a00 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
13a10 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
13a20 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
13a30 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
13a40 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
13a50 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
13a60 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
13a70 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
13a80 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
13a90 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
13aa0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
13ab0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
13ac0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
13ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
13ae0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
13af0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
13b00 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
13b10 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
13b20 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
13b30 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
13b40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
13b50 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
13b60 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
13b70 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
13b80 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
13b90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
13ba0 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
13bb0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
13bc0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
13bd0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
13be0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
13bf0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
13c00 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
13c10 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
13c20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
13c30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
13c40 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73  ect..** On all s
13c50 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
13c60 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
13c70 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
13c80 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
13c90 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
13ca0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
13cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
13cc0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
13cd0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52   method..**.** R
13ce0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
13cf0 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64  [H17392].*/.void
13d00 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
13d10 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
13d20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
13d30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
13d40 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
13d50 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35   Callbacks {H125
13d60 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a  00} <S70100>.**.
13d70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
13d80 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
13d90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
13da0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
13db0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
13dc0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
13dd0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
13de0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  t argument..** T
13df0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
13e00 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
13e10 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
13e20 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
13e30 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
13e40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
13e50 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
13e60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13e70 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
13e80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
13e90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
13ea0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
13eb0 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
13ec0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
13ed0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
13ee0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
13ef0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
13f00 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
13f10 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
13f20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
13f30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
13f40 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
13f50 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
13f60 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
13f70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
13f80 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
13f90 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
13fa0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
13fb0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
13fc0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
13fd0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
13fe0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
13ff0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
14000 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
14010 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
14020 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
14030 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
14040 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
14050 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
14060 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
14070 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61  error.  If the a
14080 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14090 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
140a0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
140b0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
140c0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
140d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
140e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
140f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14100 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
14110 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
14120 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
14130 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
14140 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
14150 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
14160 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
14170 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
14180 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
14190 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
141a0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
141b0 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61  ok.  When the ca
141c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
141d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
141e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
141f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
14200 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
14210 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
14220 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
14230 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
14240 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
14250 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
14260 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
14270 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ied. .**.** The 
14280 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14290 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
142a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
142b0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
142c0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
142d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
142e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
142f0 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73 65  nterface. The se
14300 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
14310 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
14320 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
14330 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
14340 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
14350 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14360 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
14370 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
14380 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ized. The third 
14390 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
143a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
143b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
143c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
143d0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
143e0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
143f0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
14400 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
14410 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
14420 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f  .** If the actio
14430 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
14440 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
14450 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
14460 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
14470 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
14480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14490 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
144a0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
144b0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
144c0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
144d0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
144e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
144f0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
14500 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
14510 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
14520 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
14530 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
14540 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
14550 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
14560 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
14570 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
14580 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
14590 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 74  a table..** If t
145a0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
145b0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
145c0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
145d0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
145e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
145f0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
14600 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
14610 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
14620 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
14630 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
14640 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
14650 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
14660 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
14670 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
14680 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
14690 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
146a0 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
146b0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
146c0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
146d0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
146e0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
146f0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
14700 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
14710 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
14720 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
14730 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
14740 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
14750 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
14760 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
14770 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
14780 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
14790 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
147a0 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
147b0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
147c0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
147d0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
147e0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
147f0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
14800 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
14810 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
14820 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
14830 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
14840 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
14850 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
14860 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
14870 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
14880 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
14890 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
148a0 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
148b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
148c0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
148d0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
148e0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
148f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
14900 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
14910 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
14920 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
14930 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
14940 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
14950 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
14960 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
14970 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
14980 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
14990 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
149a0 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
149b0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
149c0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
149d0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
149e0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
149f0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f  horizer..**.** O
14a00 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
14a10 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
14a20 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
14a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14a40 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
14a50 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
14a60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14a70 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
14a80 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
14a90 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65  ll.  Disable the
14aa0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
14ab0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
14ac0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
14ad0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
14ae0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14af0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
14b00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14b10 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
14b20 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
14b30 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
14b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14b50 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
14b60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14b70 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
14b80 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
14b90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
14ba0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
14bb0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
14bc0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
14bd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
14be0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
14bf0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
14c00 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
14c10 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * When [sqlite3_
14c20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
14c30 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
14c40 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
14c50 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
14c60 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72  ight be reprepar
14c70 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
14c80 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
14c90 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
14ca0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
14cb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
14cc0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
14cd0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
14ce0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
14cf0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
14d00 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
14d10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14d20 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  ]..**.** Note th
14d30 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
14d40 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
14d50 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
14d60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
14d70 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
14d80 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
14d90 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
14da0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
14db0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
14dc0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
14dd0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
14de0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
14df0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
14e00 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
14e10 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
14e20 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
14e30 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
14e40 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
14e50 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
14e60 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a  ema change..**.*
14e70 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
14e80 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32  ** [H12501] [H12
14e90 35 30 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48  502] [H12503] [H
14ea0 31 32 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20  12504] [H12505] 
14eb0 5b 48 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37  [H12506] [H12507
14ec0 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48  ] [H12510].** [H
14ed0 31 32 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20  12511] [H12512] 
14ee0 5b 48 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31  [H12520] [H12521
14ef0 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e  ] [H12522].*/.in
14f00 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
14f10 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
14f20 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
14f30 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
14f40 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
14f50 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
14f60 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
14f70 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
14f80 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
14f90 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
14fa0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
14fb0 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e  H12590} <H12500>
14fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
14fd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
14fe0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
14ff0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15000 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
15010 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
15020 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
15030 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
15040 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
15050 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
15060 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
15070 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
15080 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
15090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
150a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
150b0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
150c0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
150d0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
150e0 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
150f0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
15100 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
15110 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
15120 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
15130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
15140 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
15150 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
15160 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
15170 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
15180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15190 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
151a0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30  on Codes {H12550
151b0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
151c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
151d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
151e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
151f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
15200 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
15210 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
15220 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
15230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
15240 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
15250 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15260 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
15270 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
15280 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
15290 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
152a0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
152b0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
152c0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
152d0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
152e0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
152f0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
15300 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
15310 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
15320 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
15330 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
15340 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
15350 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
15360 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
15370 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
15380 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
15390 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
153a0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
153b0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
153c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
153d0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
153e0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
153f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15400 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
15410 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
15420 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
15430 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
15440 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
15450 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
15460 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
15470 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
15480 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
15490 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
154a0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
154b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
154c0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
154d0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
154e0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
154f0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
15500 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
15510 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
15520 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
15530 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
15540 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
15550 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
15560 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20  ts:.** [H12551] 
15570 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33  [H12552] [H12553
15580 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a  ] [H12554].*/./*
15590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
155a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
155b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
155c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
155d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
155e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
155f0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
15600 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
15610 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
15620 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
15630 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
15640 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
15650 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
15660 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15670 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15680 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
15690 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
156a0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
156b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
156c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
156d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
156e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
156f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15700 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15710 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15720 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
15730 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
15740 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
15750 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
15760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15770 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
15780 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
15790 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
157a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
157b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
157c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
157d0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
157e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
157f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15800 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15810 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
15820 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
15830 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15840 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15850 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15860 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
15870 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
15880 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15890 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
158a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158b0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
158c0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
158d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
158e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
158f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15900 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
15910 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
15920 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15930 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15950 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
15960 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
15970 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
15980 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
159a0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
159b0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
159c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
159d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
159e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
159f0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
15a00 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
15a10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15a20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15a30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
15a40 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
15a50 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
15a60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
15a70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
15a90 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
15aa0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
15ab0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
15ac0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15ae0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
15af0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
15b00 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
15b10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15b20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
15b30 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
15b40 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
15b50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15b60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15b70 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
15b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
15b90 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
15ba0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
15bb0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
15bc0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
15bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
15be0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15bf0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
15c00 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15c10 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
15c20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
15c30 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
15c40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15c50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15c60 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
15c70 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
15c80 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
15c90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15ca0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15cb0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
15cc0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
15cd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
15ce0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
15cf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15d00 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
15d10 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
15d20 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
15d30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15d40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15d50 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
15d60 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
15d70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
15d80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15da0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
15db0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
15dc0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
15dd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15df0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
15e00 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
15e10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
15e20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e40 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
15e50 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
15e60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15e70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e90 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
15ea0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
15eb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
15ec0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
15ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15ee0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
15ef0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
15f00 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
15f10 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
15f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
15f30 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
15f40 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
15f50 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
15f60 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
15f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
15f80 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
15f90 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
15fa0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
15fb0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
15fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
15fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15fe0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
15ff0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
16000 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
16010 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
16020 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32  g Functions {H12
16030 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  280} <S60400>.**
16040 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
16050 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
16060 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
16070 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
16080 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
16090 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
160a0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
160b0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
160c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
160d0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
160e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
160f0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
16100 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
16110 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
16120 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
16130 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
16140 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
16150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
16160 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  * The callback r
16170 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72  eturns a UTF-8 r
16180 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
16190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
161a0 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61  xt.** as the sta
161b0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
161c0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20  ins executing.  
161d0 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  Additional callb
161e0 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73  acks occur.** as
161f0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
16200 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
16210 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
16220 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
16230 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
16240 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
16250 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
16260 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  s the trigger..*
16270 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
16280 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
16290 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
162a0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
162b0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
162c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
162d0 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72  inishes.  The pr
162e0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
162f0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
16300 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
16310 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
16320 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
16330 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
16340 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
16350 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
16360 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  run..**.** Requi
16370 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
16380 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48  281] [H12282] [H
16390 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20  12283] [H12284] 
163a0 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37  [H12285] [H12287
163b0 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32  ] [H12288] [H122
163c0 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a  89].** [H12290].
163d0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
163e0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
163f0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
16400 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
16410 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
16420 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
16430 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
16440 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
16450 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
16460 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
16470 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
16480 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
16490 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
164a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
164b0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
164c0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
164d0 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  10} <S60400>.**.
164e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
164f0 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
16500 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
16510 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73   the.** progress
16520 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74   callback - that
16530 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
16540 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
16550 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  long.** running 
16560 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
16570 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
16580 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a  te3_step()] and.
16590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
165a0 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78  table()].  An ex
165b0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
165c0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
165d0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
165e0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
165f0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
16600 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67  *.** If the prog
16610 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
16620 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
16630 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
16640 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
16650 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
16660 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
16670 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
16680 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
16690 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
166a0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
166b0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
166c0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64  ndler must not d
166d0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
166e0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
166f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16700 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
16710 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
16720 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
16730 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
16740 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
16750 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
16760 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
16770 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
16780 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
16790 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
167a0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
167b0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
167c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
167d0 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32  ** [H12911] [H12
167e0 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48  912] [H12913] [H
167f0 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20  12914] [H12915] 
16800 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37  [H12916] [H12917
16810 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f  ] [H12918].**.*/
16820 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
16830 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
16840 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
16850 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
16860 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
16870 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
16880 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
16890 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
168a0 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
168b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
168c0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
168d0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
168e0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
168f0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
16900 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
16910 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
16920 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
16930 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
16940 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
16950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
16960 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
16970 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
16980 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
16990 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
169a0 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
169b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
169c0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
169d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
169e0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
169f0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
16a00 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
16a10 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
16a20 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
16a30 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
16a40 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
16a50 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
16a60 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
16a70 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
16a80 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
16a90 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
16aa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
16ab0 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
16ac0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
16ad0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
16ae0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
16af0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
16b00 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
16b10 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
16b20 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
16b30 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
16b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
16b50 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
16b60 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
16b70 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
16b80 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
16b90 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
16ba0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
16bb0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
16bc0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
16bd0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
16be0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
16bf0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
16c00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
16c10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16c20 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
16c30 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
16c40 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
16c50 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
16c60 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
16c70 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
16c80 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
16c90 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
16ca0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
16cb0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
16cc0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
16cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
16ce0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
16cf0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
16d00 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
16d10 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
16d20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
16d30 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
16d40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16d50 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
16d60 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
16d70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
16d80 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
16d90 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
16da0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
16db0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
16dc0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
16dd0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
16de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
16df0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
16e00 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
16e10 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
16e20 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
16e30 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
16e40 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
16e50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
16e60 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
16e70 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
16e80 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a  TEX] flags:.**.*
16e90 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
16ea0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
16eb0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
16ec0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
16ed0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
16ee0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
16ef0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
16f00 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
16f10 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
16f20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
16f30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
16f40 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
16f50 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
16f60 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
16f70 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
16f80 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
16f90 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
16fa0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
16fb0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
16fc0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
16fd0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
16fe0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
16ff0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
17000 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
17010 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
17020 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
17030 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
17040 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
17050 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
17060 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
17070 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
17080 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
17090 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
170a0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
170b0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
170c0 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
170d0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
170e0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
170f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
17100 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
17110 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
17120 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
17130 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
17140 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
17150 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
17160 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17170 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
17180 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
17190 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
171a0 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
171b0 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
171c0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
171d0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
171e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
171f0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
17200 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
17210 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  UTEX] flags,.** 
17220 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
17230 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
17240 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
17250 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
17260 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
17270 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
17280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17290 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
172a0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
172b0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
172c0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
172d0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
172e0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
172f0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
17300 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
17310 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   If the.** [SQLI
17320 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
17330 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
17340 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
17350 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
17360 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
17370 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
17380 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
17390 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
173a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
173b0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
173c0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
173d0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  -time..**.** If 
173e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
173f0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
17400 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
17410 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
17420 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
17430 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
17440 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
17450 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
17460 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
17470 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
17480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17490 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
174a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
174b0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
174c0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
174d0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
174e0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
174f0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
17500 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
17510 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
17520 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
17530 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
17540 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
17550 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
17560 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
17570 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
17580 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
17590 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
175a0 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
175b0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
175c0 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
175d0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
175e0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
175f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
17600 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
17610 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
17620 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
17630 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
17640 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
17650 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
17660 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
17670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17680 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
17690 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
176a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
176b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
176c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
176d0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
176e0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
176f0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
17700 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
17710 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
17720 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
17730 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
17740 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
17750 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
17760 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
17770 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
17780 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
17790 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
177a0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
177b0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
177c0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
177d0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
177e0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
177f0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
17800 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
17810 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
17820 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
17830 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
17840 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
17850 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
17860 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
17870 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
17880 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
17890 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
178a0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
178b0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
178c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
178d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
178e0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
178f0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
17900 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37 30   [H12701] [H1270
17910 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 32  2] [H12703] [H12
17920 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48  704] [H12706] [H
17930 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d 20  12707] [H12709] 
17940 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32  [H12711].** [H12
17950 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48  712] [H12713] [H
17960 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d 20  12714] [H12717] 
17970 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32 31  [H12719] [H12721
17980 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e  ] [H12723].*/.in
17990 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
179a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
179b0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
179c0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
179d0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
179e0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
179f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
17a00 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
17a10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
17a20 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
17a30 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
17a40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
17a50 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
17a60 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
17a70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
17a80 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
17a90 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
17aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
17ab0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
17ac0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
17ad0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
17ae0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
17af0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
17b00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
17b10 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
17b20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
17b30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
17b40 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
17b50 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
17b60 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
17b70 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
17b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17b90 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
17ba0 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31  And Messages {H1
17bb0 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  2800} <S60200>.*
17bc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
17bd0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
17be0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17bf0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
17c00 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
17c10 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17c20 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
17c30 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
17c40 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
17c50 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
17c60 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
17c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
17c80 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
17c90 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
17ca0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17cb0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
17cc0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
17cd0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
17ce0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
17cf0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68  s undefined.  Th
17d00 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
17d10 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
17d20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
17d30 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
17d40 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
17d50 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
17d60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
17d70 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
17d80 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
17d90 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
17da0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
17db0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
17dc0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
17dd0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
17de0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
17df0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
17e00 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
17e10 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
17e20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
17e30 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72  tively..** Memor
17e40 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
17e50 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
17e60 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
17e70 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
17e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
17e90 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
17ea0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
17eb0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
17ec0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
17ed0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
17ee0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
17ef0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
17f00 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
17f10 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
17f20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
17f30 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
17f40 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
17f50 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
17f60 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
17f70 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
17f80 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
17f90 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
17fa0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
17fb0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
17fc0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
17fd0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
17fe0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
17ff0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
18000 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
18010 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
18020 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
18030 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
18040 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
18050 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
18060 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
18070 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
18080 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
18090 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
180a0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
180b0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
180c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
180d0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
180e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
180f0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
18100 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
18110 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
18120 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
18130 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
18140 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
18150 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
18160 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
18170 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
18180 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
18190 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
181a0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
181b0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
181c0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
181d0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
181e0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
181f0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
18200 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
18210 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
18220 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
18230 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
18240 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
18250 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
18260 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  t..**.** Require
18270 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30  ments:.** [H1280
18280 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32  1] [H12802] [H12
18290 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48  803] [H12807] [H
182a0 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a  12808] [H12809].
182b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
182c0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
182d0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
182e0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
182f0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
18300 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
18310 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
18320 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
18330 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
18340 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
18350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
18360 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
18370 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31  ect {H13000} <H1
18380 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  3010>.** KEYWORD
18390 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
183a0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
183b0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
183c0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
183d0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
183e0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
183f0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
18400 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
18410 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
18420 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
18430 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
18440 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
18450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
18460 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
18470 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
18480 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
18490 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
184a0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
184b0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
184c0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
184d0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
184e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
184f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
18500 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
18510 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
18520 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
18530 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
18540 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
18550 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
18560 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
18570 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
18580 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
18590 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
185a0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
185b0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
185c0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
185d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
185e0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
185f0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
18600 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
18610 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
18620 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
18630 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
18640 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
18650 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
18660 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
18670 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
18680 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
18690 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
186a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
186b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
186c0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
186d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
186e0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
186f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
18700 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31  -time Limits {H1
18710 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a  2760} <S20600>.*
18720 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
18730 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
18740 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
18750 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
18760 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
18770 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
18780 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
18790 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
187a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
187b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
187c0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
187d0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
187e0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
187f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
18800 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
18810 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
18820 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
18830 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
18840 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
18850 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
18860 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18870 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
18880 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
18890 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
188a0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
188b0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
188c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
188d0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
188e0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
188f0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
18900 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
18910 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
18920 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
18930 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  Z there is a .**
18940 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
18950 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
18960 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
18970 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65  -time C preproce
18980 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64  ssor macro named
18990 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53   .** [limits | S
189a0 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a  QLITE_MAX_XYZ]..
189b0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
189c0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
189d0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
189e0 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
189f0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
18a00 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
18a10 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
18a20 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
18a30 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
18a40 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
18a50 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
18a60 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
18a70 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
18a80 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
18a90 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
18aa0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
18ab0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
18ac0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
18ad0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
18ae0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
18af0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
18b00 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
18b10 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
18b20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
18b30 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
18b40 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
18b50 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
18b60 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
18b70 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
18b80 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
18b90 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
18ba0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
18bb0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
18bc0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
18bd0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
18be0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
18bf0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
18c00 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
18c10 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
18c20 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
18c30 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
18c40 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
18c50 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
18c60 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
18c70 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
18c80 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
18c90 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
18ca0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
18cb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18cc0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
18cd0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
18ce0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
18cf0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
18d00 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
18d10 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
18d20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
18d30 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
18d40 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
18d50 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
18d60 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
18d70 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
18d80 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
18d90 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
18da0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
18db0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ses..**.** Requi
18dc0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
18dd0 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48  762] [H12766] [H
18de0 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71  12769].*/.int sq
18df0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
18e00 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
18e10 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
18e20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
18e30 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
18e40 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c  ories {H12790} <
18e50 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H12760>.** KEYWO
18e60 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
18e70 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74  gory} {limit cat
18e80 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
18e90 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
18ea0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
18eb0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
18ec0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
18ed0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
18ee0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
18ef0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
18f00 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
18f10 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
18f20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
18f30 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
18f40 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
18f50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
18f60 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
18f70 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
18f80 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
18f90 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18fa0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
18fb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18fc0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
18fd0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
18fe0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
18ff0 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
19000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
19010 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
19020 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
19030 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
19040 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
19050 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19060 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
19070 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
19080 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
19090 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
190a0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
190b0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
190c0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
190d0 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
190e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
190f0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
19100 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
19110 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
19120 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
19130 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
19140 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
19150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19160 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
19170 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
19180 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
19190 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
191a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
191b0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
191c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
191d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
191e0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
191f0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
19200 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
19210 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
19220 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
19230 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
19240 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
19250 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
19260 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
19270 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
19280 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
19290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
192a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
192b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
192c0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
192d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
192e0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
192f0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
19300 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
19310 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
19320 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
19330 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
19340 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
19350 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
19360 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a  abases].</dd>.**
19370 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
19380 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
19390 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
193a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
193b0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
193c0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
193d0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
193e0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
193f0 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
19400 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
19410 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
19420 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
19430 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
19440 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
19450 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
19460 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
19470 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
19480 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
19490 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
194a0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
194b0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
194c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
194d0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
194e0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
194f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
19500 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
19510 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
19520 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
19530 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
19540 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
19550 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
19560 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
19570 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
19580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
19590 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
195a0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
195b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
195c0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
195d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
195e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
195f0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
19600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
19610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19620 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
19630 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
19640 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
19650 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
19660 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
19670 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
19680 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
19690 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
196a0 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e  H13010} <S10000>
196b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
196c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
196d0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
196e0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
196f0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
19700 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
19710 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
19720 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
19730 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
19740 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
19750 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19760 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
19770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19780 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
19790 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
197a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
197b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
197c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
197d0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
197e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
197f0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
19800 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
19810 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
19820 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
19830 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
19840 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
19850 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
19860 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
19870 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
19880 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
19890 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
198a0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
198b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
198c0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
198d0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
198e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
198f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
19900 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
19910 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49   UTF-16..**.** I
19920 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
19930 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
19940 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
19950 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
19960 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
19970 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66  o terminator. If
19980 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
19990 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
199a0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
199b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
199c0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
199d0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
199e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
199f0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
19a00 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
19a10 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
19a20 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
19a30 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
19a40 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
19a50 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
19a60 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
19a70 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
19a80 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
19a90 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
19aa0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
19ab0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
19ac0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
19ad0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
19ae0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
19af0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
19b00 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
19b10 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
19b20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
19b30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
19b40 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
19b50 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
19b60 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
19b70 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20  **.** If pzTail 
19b80 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
19b90 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
19ba0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
19bb0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
19bc0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
19bd0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
19be0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
19bf0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19c00 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
19c10 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
19c20 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
19c30 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
19c40 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
19c50 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
19c60 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
19c70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
19c80 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
19c90 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
19ca0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
19cb0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
19cc0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
19cd0 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68  _step()].  If th
19ce0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
19cf0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
19d00 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  ** to NULL.  If 
19d10 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
19d20 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
19d30 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
19d40 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
19d50 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
19d60 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
19d70 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
19d80 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
19d90 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
19da0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
19db0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
19dc0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19dd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19de0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
19df0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
19e00 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
19e10 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
19e20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  NULL..**.** On s
19e30 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
19e40 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c  OK] is returned,
19e50 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
19e60 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
19e70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
19e80 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
19e90 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
19ea0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19eb0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
19ec0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
19ed0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
19ee0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
19ef0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
19f00 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
19f10 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
19f20 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
19f30 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
19f40 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20  couraged..** In 
19f50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
19f60 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
19f70 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
19f80 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
19f90 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
19fa0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
19fb0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
19fc0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
19fd0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
19fe0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
19ff0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
1a000 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
1a010 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69   a differently i
1a020 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a  n two ways:.**.*
1a030 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
1a040 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
1a050 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
1a060 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
1a070 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
1a080 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
1a090 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
1a0a0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
1a0b0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
1a0c0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1a0d0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
1a0e0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
1a0f0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20   run it again.  
1a100 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
1a110 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
1a120 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
1a130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
1a140 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
1a150 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a160 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
1a170 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
1a180 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
1a190 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
1a1a0 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f  havior, [SQLITE_
1a1b0 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f  SCHEMA] is.** no
1a1c0 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
1a1d0 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74    Calling [sqlit
1a1e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a1f0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
1a200 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
1a210 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
1a220 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
1a230 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
1a240 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
1a250 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
1a260 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
1a270 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
1a280 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20  EMA] return..** 
1a290 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1a2a0 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  .** When an erro
1a2b0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1a2c0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1a2d0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1a2e0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1a2f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1a300 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1a310 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61  odes].  The lega
1a320 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
1a330 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
1a340 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
1a350 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
1a360 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
1a370 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
1a380 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64  ** and you would
1a390 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1a3a0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1a3b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1a3c0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1a3d0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1a3e0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1a3f0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1a400 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1a410 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1a420 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1a430 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1a440 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1a450 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1a460 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
1a470 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1a480 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48  :.** [H13011] [H
1a490 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20  13012] [H13013] 
1a4a0 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35  [H13014] [H13015
1a4b0 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30  ] [H13016] [H130
1a4c0 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a  19] [H13021].**.
1a4d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1a4e0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1a4f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a500 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1a510 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a520 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1a530 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1a540 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1a550 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1a560 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a570 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1a580 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1a590 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a5a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a5b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a5c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a5d0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1a5e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a5f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a600 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a610 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a620 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1a630 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a640 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a650 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a660 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a670 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a680 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1a690 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a6a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a6b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a6c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a6d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a6e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a6f0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a700 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a710 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a720 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a730 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a740 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a750 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1a770 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1a780 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a790 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a7a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a7b0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a7c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a7d0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1a7e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a7f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a800 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a810 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a820 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a830 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a840 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a860 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1a870 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a880 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a890 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a8a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1a8b0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1a8c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a8d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a8e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a8f0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1a900 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a910 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1a920 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1a930 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1a940 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1a950 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1a960 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1a970 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1a980 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1a990 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1a9a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1a9b0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1a9c0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1a9d0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1a9e0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1a9f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1aa00 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1aa10 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
1aa20 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
1aa30 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1aa40 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1aa50 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1aa60 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1aa70 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1aa80 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1aa90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1aaa0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1aab0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1aac0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1aad0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1aae0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1aaf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ab00 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  2()]..**.** Requ
1ab10 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1ab20 33 31 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b  3101] [H13102] [
1ab30 48 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13103].*/.const
1ab40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1ab50 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1ab60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1ab70 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
1ab80 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1ab90 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30  e Object {H15000
1aba0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
1abb0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1abc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1abd0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1abe0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1abf0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1ac00 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1ac10 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1ac20 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1ac30 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1ac40 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1ac50 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1ac60 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1ac70 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1ac80 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1ac90 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1aca0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1acb0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1acc0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1acd0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1ace0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1acf0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1ad00 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1ad10 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1ad20 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1ad30 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1ad40 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1ad50 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1ad60 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1ad70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1ad80 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1ad90 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1ada0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1adb0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1adc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1add0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1ade0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1adf0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1ae00 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1ae10 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1ae20 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1ae30 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1ae40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1ae50 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1ae60 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1ae70 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1ae80 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1ae90 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1aea0 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1aeb0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1aec0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1aed0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1aee0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1aef0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1af00 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1af10 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1af20 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1af30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1af40 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1af50 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1af60 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1af70 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1af80 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1af90 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1afa0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
1afb0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
1afc0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
1afd0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
1afe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1aff0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
1b000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1b010 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
1b020 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1b030 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1b040 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1b050 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1b060 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1b070 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1b080 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
1b090 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
1b0a0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
1b0b0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1b0c0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
1b0d0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1b0e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
1b0f0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
1b100 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
1b110 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1b120 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1b130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1b140 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
1b150 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
1b160 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1b170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1b180 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1b190 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1b1a0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1b1b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1b1c0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1b1d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1b1e0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1b1f0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
1b200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1b210 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
1b220 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
1b230 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
1b240 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
1b250 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
1b260 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b270 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
1b280 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
1b290 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
1b2a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1b2b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
1b2c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1b2d0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
1b2e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1b2f0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
1b300 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1b310 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1b320 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1b330 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1b340 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1b350 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1b360 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
1b370 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
1b380 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20  Object {H16001} 
1b390 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
1b3a0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
1b3b0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
1b3c0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
1b3d0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
1b3e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1b3f0 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
1b400 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1b410 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1b420 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
1b430 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1b440 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1b450 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1b460 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1b470 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1b480 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
1b490 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
1b4a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
1b4b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
1b4c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
1b4d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
1b4e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
1b4f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1b500 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1b510 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
1b520 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
1b530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1b540 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
1b550 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
1b560 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
1b570 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
1b580 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
1b590 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1b5a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
1b5b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
1b5c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b5d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1b5e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1b5f0 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c  ments {H13500} <
1b600 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S70300>.** KEYWO
1b610 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1b620 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1b630 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1b640 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1b650 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1b660 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1b670 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1b680 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1b690 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
1b6a0 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
1b6b0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1b6c0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
1b6d0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
1b6e0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
1b6f0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
1b700 61 6d 65 74 65 72 5d 20 69 6e 20 6f 6e 65 20 6f  ameter] in one o
1b710 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
1b720 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1b730 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1b740 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1b750 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1b760 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1b770 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1b780 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
1b790 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
1b7a0 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
1b7b0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1b7c0 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
1b7d0 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1b7e0 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
1b7f0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1b800 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1b810 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1b820 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1b830 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1b840 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1b850 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1b860 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b870 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1b880 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1b890 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1b8a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b8b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1b8c0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1b8d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1b8e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1b8f0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1b900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1b910 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1b920 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1b930 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1b940 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1b950 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1b960 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1b970 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1b980 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1b990 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1b9a0 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1b9b0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1b9c0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1b9d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1b9e0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1b9f0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1ba00 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1ba10 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1ba20 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1ba30 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1ba40 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1ba50 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1ba60 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1ba70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ba80 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ba90 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1baa0 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
1bab0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1bac0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1bad0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1bae0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1baf0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1bb00 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1bb10 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1bb20 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1bb30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1bb40 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1bb50 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1bb60 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1bb70 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1bb80 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1bb90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1bba0 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
1bbb0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1bbc0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1bbd0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1bbe0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1bbf0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1bc00 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1bc10 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1bc20 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1bc30 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1bc40 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1bc50 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1bc60 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
1bc70 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1bc80 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1bc90 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1bca0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1bcb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1bcc0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1bcd0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1bce0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1bcf0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1bd00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1bd10 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1bd20 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1bd30 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1bd40 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1bd50 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1bd60 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1bd70 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1bd80 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1bd90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1bda0 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1bdb0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1bdc0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1bdd0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1bde0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1bdf0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1be00 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1be10 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1be20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1be30 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1be40 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1be50 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1be60 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1be70 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1be80 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1be90 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1bea0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1beb0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1bec0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1bed0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1bee0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1bef0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1bf00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1bf10 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1bf20 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1bf30 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1bf40 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1bf50 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1bf60 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1bf70 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1bf80 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1bf90 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1bfa0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1bfb0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1bfc0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1bfd0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1bfe0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1bff0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1c000 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1c010 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1c020 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1c030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1c040 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1c050 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1c060 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
1c070 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
1c080 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
1c090 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
1c0a0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
1c0b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1c0c0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1c0d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1c0e0 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
1c0f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c100 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
1c110 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
1c120 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
1c130 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
1c140 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
1c150 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1c160 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1c170 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1c180 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
1c190 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1c1a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1c1b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
1c1c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c1d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1c1e0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
1c1f0 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
1c200 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1c210 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
1c220 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
1c230 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c240 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
1c250 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
1c260 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
1c270 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
1c280 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
1c290 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
1c2a0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
1c2b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c2c0 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
1c2d0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
1c2e0 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
1c2f0 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
1c300 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
1c310 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
1c320 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
1c330 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
1c340 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
1c350 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
1c360 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
1c370 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
1c380 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
1c390 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
1c3a0 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
1c3b0 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
1c3c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c3d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1c3e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1c3f0 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
1c400 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
1c410 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
1c420 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1c430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1c440 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1c450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1c460 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1c470 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1c480 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1c490 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1c4a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1c4b0 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30   [H13506] [H1350
1c4c0 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33  9] [H13512] [H13
1c4d0 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48  515] [H13518] [H
1c4e0 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20  13521] [H13524] 
1c4f0 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33  [H13527].** [H13
1c500 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48  530] [H13533] [H
1c510 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20  13536] [H13539] 
1c520 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35  [H13542] [H13545
1c530 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35  ] [H13548] [H135
1c540 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  51].**.*/.int sq
1c550 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1c560 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1c570 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1c580 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1c590 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1c5a0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
1c5b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c5c0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
1c5d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1c5e0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1c5f0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
1c600 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1c610 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
1c620 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1c630 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
1c640 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
1c650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c660 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c670 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
1c680 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1c690 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
1c6a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1c6b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c6c0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
1c6d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1c6e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1c6f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1c700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c710 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
1c720 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1c730 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
1c740 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c750 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
1c760 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c770 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1c780 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1c790 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
1c7a0 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
1c7b0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
1c7c0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1c7d0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1c7e0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1c7f0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1c800 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1c810 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1c820 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1c830 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1c840 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1c850 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1c860 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1c870 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1c880 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1c890 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1c8a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1c8b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1c8c0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1c8d0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1c8e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c8f0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
1c900 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1c910 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
1c920 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
1c930 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
1c940 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
1c950 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
1c960 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
1c970 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
1c980 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
1c990 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1c9a0 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
1c9b0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1c9c0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1c9d0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
1c9e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1c9f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1ca00 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1ca10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1ca20 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1ca30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ca40 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1ca50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1ca60 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1ca70 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  01].*/.int sqlit
1ca80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1ca90 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
1caa0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1cab0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
1cac0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
1cad0 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33  r {H13620} <S703
1cae0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1caf0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1cb00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1cb10 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1cb20 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
1cb30 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
1cb40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1cb50 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1cb60 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1cb70 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1cb80 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1cb90 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1cba0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1cbb0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1cbc0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1cbd0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1cbe0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1cbf0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1cc00 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1cc10 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1cc20 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1cc30 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1cc40 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
1cc50 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1cc60 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
1cc70 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
1cc80 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
1cc90 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
1cca0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
1ccb0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1ccc0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
1ccd0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1cce0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1ccf0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1cd00 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
1cd10 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
1cd20 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
1cd30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1cd40 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
1cd50 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1cd60 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
1cd70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1cd80 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
1cd90 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1cda0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1cdb0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1cdc0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1cdd0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1cde0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1cdf0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1ce00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1ce10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1ce20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1ce30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1ce40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1ce50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ce60 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1ce70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ce80 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1ce90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1cea0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1ceb0 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  21].*/.const cha
1cec0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1ced0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1cee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cef0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1cf00 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1cf10 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1cf20 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
1cf30 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
1cf40 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
1cf50 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1cf60 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
1cf70 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
1cf80 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
1cf90 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
1cfa0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
1cfb0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
1cfc0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1cfd0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1cfe0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
1cff0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1d000 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1d010 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1d020 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
1d030 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
1d040 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
1d050 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
1d060 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1d070 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
1d080 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
1d090 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
1d0a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1d0b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1d0c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1d0d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1d0e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1d0f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d100 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1d110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d120 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1d130 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  x()]..**.** Requ
1d140 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1d150 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3641].*/.int sql
1d160 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d170 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
1d180 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
1d190 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
1d1a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1d1b0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
1d1c0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
1d1d0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
1d1e0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1d1f0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
1d200 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1d210 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1d220 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1d230 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1d240 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1d250 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1d260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d270 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
1d280 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
1d290 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
1d2a0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
1d2b0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1d2c0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a  ts:.** [H13661].
1d2d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1d2e0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
1d2f0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1d300 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1d310 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
1d320 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1d330 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
1d340 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
1d350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1d360 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1d370 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1d380 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1d390 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1d3a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1d3b0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
1d3c0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
1d3d0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1d3e0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1d3f0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
1d400 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
1d410 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1d420 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a  .** [H13711].*/.
1d430 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1d440 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1d450 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1d460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d470 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1d480 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31  A Result Set {H1
1d490 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3720} <S10700>.*
1d4a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d4b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1d4c0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1d4d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1d4e0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1d4f0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1d500 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1d510 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
1d520 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
1d530 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1d540 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1d550 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d560 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
1d570 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
1d580 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
1d590 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d5a0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1d5b0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1d5c0 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
1d5d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d5e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1d5f0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1d600 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1d610 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1d620 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
1d630 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1d640 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1d650 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
1d660 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
1d670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
1d680 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
1d690 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
1d6a0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
1d6b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d6c0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
1d6d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d6e0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1d6f0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
1d700 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
1d710 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
1d720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1d730 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
1d740 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
1d750 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
1d760 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
1d770 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
1d780 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
1d790 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
1d7a0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
1d7b0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
1d7c0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
1d7d0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
1d7e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1d7f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
1d800 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
1d810 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
1d820 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
1d830 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
1d840 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
1d850 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
1d860 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
1d870 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
1d880 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
1d890 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
1d8a0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
1d8b0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
1d8c0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
1d8d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
1d8e0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ext..**.** Requi
1d8f0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1d900 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48  721] [H13723] [H
1d910 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20  13724] [H13725] 
1d920 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37  [H13726] [H13727
1d930 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1d940 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1d950 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1d960 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
1d970 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1d980 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
1d990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d9a0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
1d9b0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
1d9c0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
1d9d0 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20  Result {H13740} 
1d9e0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1d9f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1da00 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1da10 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1da20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1da30 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1da40 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1da50 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
1da60 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
1da70 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
1da80 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1da90 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1daa0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1dab0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1dac0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1dad0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1dae0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1daf0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1db00 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1db10 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1db20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1db30 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1db40 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1db50 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1db60 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1db70 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
1db80 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
1db90 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
1dba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dbb0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
1dbc0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1dbd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1dbe0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
1dbf0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
1dc00 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
1dc10 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
1dc20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
1dc30 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
1dc40 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
1dc50 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
1dc60 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
1dc70 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
1dc80 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1dc90 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1dca0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
1dcb0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
1dcc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dcd0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
1dce0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1dcf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
1dd00 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
1dd10 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
1dd20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1dd30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1dd40 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1dd50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1dd60 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1dd70 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1dd80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1dd90 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
1dda0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
1ddb0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1ddc0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1ddd0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1dde0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
1ddf0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1de00 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1de10 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1de20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1de30 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
1de40 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1de50 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1de60 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
1de70 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
1de80 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
1de90 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1dea0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
1deb0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
1dec0 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
1ded0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
1dee0 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
1def0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
1df00 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
1df10 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
1df20 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
1df30 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
1df40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1df50 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
1df60 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
1df70 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
1df80 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
1df90 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1dfa0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
1dfb0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
1dfc0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1dfd0 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
1dfe0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1dff0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1e000 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1e010 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1e020 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1e030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e040 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1e050 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1e060 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1e070 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1e080 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1e090 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31  ents:.** [H13741
1e0a0 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37  ] [H13742] [H137
1e0b0 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31  43] [H13744] [H1
1e0c0 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b  3745] [H13746] [
1e0d0 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66  H13748].**.** If
1e0e0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1e0f0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1e100 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1e110 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1e120 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
1e130 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1e140 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
1e150 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
1e160 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
1e170 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
1e180 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1e190 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1e1a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1e1b0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e1c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1e1d0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
1e1e0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e1f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1e200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1e210 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
1e220 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1e230 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1e240 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1e250 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1e260 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e280 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
1e290 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e2a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1e2b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1e2c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
1e2d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e2e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1e2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1e300 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1e310 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1e320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1e330 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
1e340 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
1e350 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
1e360 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
1e370 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1e380 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1e390 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
1e3a0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1e3b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1e3c0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
1e3d0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
1e3e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
1e3f0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
1e400 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
1e410 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
1e420 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
1e430 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
1e440 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
1e450 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
1e460 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
1e470 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
1e480 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
1e490 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
1e4a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
1e4b0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
1e4c0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
1e4d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1e4e0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1e4f0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
1e500 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
1e510 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
1e520 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
1e530 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1e540 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1e550 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1e560 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
1e570 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1e580 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1e590 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
1e5a0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
1e5b0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
1e5c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
1e5d0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
1e5e0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
1e5f0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
1e600 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
1e610 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
1e620 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
1e630 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
1e640 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
1e650 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
1e660 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
1e670 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
1e680 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
1e690 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
1e6a0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
1e6b0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
1e6c0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
1e6d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
1e6e0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
1e6f0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
1e700 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
1e710 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
1e720 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
1e730 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
1e740 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
1e750 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
1e760 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
1e770 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
1e780 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
1e790 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
1e7a0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
1e7b0 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ues..**.** Requi
1e7c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e7d0 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48  761] [H13762] [H
1e7e0 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13763].*/.const 
1e7f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1e800 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
1e810 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1e840 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
1e850 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1e860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
1e870 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
1e880 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
1e890 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
1e8a0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
1e8b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
1e8c0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
1e8d0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
1e8e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e8f0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1e900 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1e910 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
1e920 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
1e930 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
1e940 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
1e950 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1e960 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
1e970 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
1e980 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
1e990 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
1e9a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
1e9b0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
1e9c0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
1e9d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e9e0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
1e9f0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
1ea00 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
1ea10 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
1ea20 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
1ea30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
1ea40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1ea50 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1ea60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ea70 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
1ea80 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
1ea90 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
1eaa0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1eab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eac0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
1ead0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
1eae0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
1eaf0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1eb00 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
1eb10 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
1eb20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
1eb30 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
1eb40 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
1eb50 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
1eb60 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
1eb70 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
1eb80 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
1eb90 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
1eba0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
1ebb0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
1ebc0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
1ebd0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
1ebe0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
1ebf0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
1ec00 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
1ec10 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
1ec20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ec30 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
1ec40 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
1ec50 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
1ec60 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
1ec70 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
1ec80 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
1ec90 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
1eca0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
1ecb0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
1ecc0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
1ecd0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1ece0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
1ecf0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
1ed00 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
1ed10 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1ed20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
1ed30 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
1ed40 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
1ed50 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
1ed60 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
1ed70 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
1ed80 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
1ed90 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
1eda0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
1edb0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
1edc0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
1edd0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
1ede0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
1edf0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
1ee00 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
1ee10 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
1ee20 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
1ee30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
1ee40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
1ee50 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
1ee60 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
1ee70 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
1ee80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ee90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
1eea0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
1eeb0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
1eec0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
1eed0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
1eee0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
1eef0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
1ef00 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
1ef10 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
1ef20 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
1ef30 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
1ef40 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
1ef50 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
1ef60 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
1ef70 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
1ef80 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
1ef90 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
1efa0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
1efb0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
1efc0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
1efd0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
1efe0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
1eff0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
1f000 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
1f010 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
1f020 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
1f030 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
1f040 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
1f050 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
1f060 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
1f070 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
1f080 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
1f090 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
1f0a0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
1f0b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1f0c0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
1f0d0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
1f0e0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
1f0f0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
1f100 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
1f110 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
1f120 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
1f130 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
1f140 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
1f150 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
1f160 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
1f170 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1f180 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
1f190 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1f1a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
1f1b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1f1c0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
1f1d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
1f1e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
1f1f0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
1f200 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
1f210 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
1f220 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
1f230 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
1f240 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
1f250 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
1f260 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
1f270 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
1f280 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1f290 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
1f2a0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
1f2b0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
1f2c0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
1f2d0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
1f2e0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
1f2f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
1f300 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
1f310 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
1f320 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
1f330 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1f340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1f350 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
1f360 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
1f370 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
1f380 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
1f390 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
1f3a0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
1f3b0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
1f3c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
1f3d0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
1f3e0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
1f3f0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
1f400 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
1f410 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
1f420 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
1f430 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
1f440 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
1f450 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
1f460 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
1f470 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
1f480 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
1f490 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
1f4a0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1f4b0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
1f4c0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
1f4d0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
1f4e0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1f4f0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
1f500 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
1f510 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
1f520 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
1f530 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
1f540 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
1f550 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
1f560 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
1f570 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
1f580 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
1f590 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f5a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1f5b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f5c0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
1f5d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
1f5e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f5f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1f600 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
1f610 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
1f620 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
1f630 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
1f640 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
1f650 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
1f660 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
1f670 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
1f680 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
1f690 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1f6a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1f6b0 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33  * [H13202] [H153
1f6c0 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31  04] [H15306] [H1
1f6d0 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a  5308] [H15310].*
1f6e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
1f6f0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
1f700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f710 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
1f720 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
1f730 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
1f740 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
1f750 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1f760 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
1f770 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
1f780 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
1f790 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1f7a0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d  nts:.** [H13771]
1f7b0 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74   [H13772].*/.int
1f7c0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
1f7d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1f7e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1f7f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
1f800 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
1f810 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31   {H10265} <S1011
1f820 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45  0><S10120>.** KE
1f830 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
1f840 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
1f850 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
1f860 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
1f870 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
1f880 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
1f890 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
1f8a0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
1f8b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
1f8c0 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
1f8d0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
1f8e0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
1f8f0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
1f900 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
1f910 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
1f920 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1f930 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
1f940 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
1f950 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
1f960 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
1f970 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
1f980 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
1f990 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
1f9a0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
1f9b0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
1f9c0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
1f9d0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
1f9e0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
1f9f0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
1fa00 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1fa10 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
1fa20 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
1fa30 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
1fa40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fa50 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
1fa60 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
1fa70 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1fa80 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
1fa90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
1faa0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
1fab0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
1fac0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
1fad0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
1fae0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
1faf0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1fb00 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
1fb10 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
1fb20 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
1fb30 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
1fb40 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
1fb50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
1fb60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1fb70 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
1fb80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
1fb90 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
1fba0 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
1fbb0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
1fbc0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1fbd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
1fbe0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
1fbf0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
1fc00 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
1fc10 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
1fc20 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
1fc30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
1fc40 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
1fc50 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1fc60 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
1fc70 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
1fc80 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1fc90 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
1fca0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
1fcb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fcc0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
1fcd0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
1fce0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
1fcf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1fd00 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
1fd10 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
1fd20 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
1fd30 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
1fd40 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
1fd50 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
1fd60 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
1fd70 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20   index 0..**.** 
1fd80 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
1fd90 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
1fda0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
1fdb0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
1fdc0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
1fdd0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
1fde0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
1fdf0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1fe00 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1fe10 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
1fe20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
1fe30 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
1fe40 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1fe50 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
1fe60 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
1fe70 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
1fe80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fe90 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
1fea0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
1feb0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
1fec0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
1fed0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
1fee0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fef0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
1ff00 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
1ff10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1ff20 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
1ff30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1ff40 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
1ff50 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
1ff60 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
1ff70 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
1ff80 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
1ff90 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
1ffa0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ffb0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
1ffc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1ffd0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
1ffe0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
1fff0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
20000 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
20010 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
20020 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
20030 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
20040 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
20050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
20060 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
20070 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
20080 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
20090 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
200a0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
200b0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
200c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
200d0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
200e0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
200f0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
20100 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
20110 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
20120 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
20130 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
20140 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
20150 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
20160 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
20170 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
20180 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
20190 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
201a0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
201b0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
201c0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
201d0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
201e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
201f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
20200 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
20210 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
20220 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
20230 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
20240 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
20250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20260 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
20270 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
20280 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
20290 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
202a0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
202b0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
202c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
202d0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
202e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
202f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
20300 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
20310 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
20320 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
20330 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
20340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20350 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
20360 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
20370 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
20380 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
20390 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
203a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
203b0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
203c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
203d0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
203e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
203f0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
20400 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
20410 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
20420 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
20430 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20440 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
20450 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
20460 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
20470 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
20480 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
20490 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
204a0 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
204b0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
204c0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
204d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
204e0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
204f0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
20500 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
20510 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
20520 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
20540 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
20550 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
20560 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
20570 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
20580 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
20590 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
205a0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
205b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
205c0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
205d0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
205e0 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
205f0 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
20600 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
20610 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
20620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
20630 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
20640 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
20650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20660 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
20670 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
20680 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
20690 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
206a0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
206b0 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
206c0 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
206d0 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
206e0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
206f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
20700 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20710 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
20720 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
20730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
20740 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
20750 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20760 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
20770 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
20780 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
20790 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
207a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
207b0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
207c0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
207d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
207e0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
207f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
20800 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
20810 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
20820 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
20830 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
20840 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
20850 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
20860 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
20870 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
20880 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
20890 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
208a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
208b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
208c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
208d0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
208e0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
208f0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
20900 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
20910 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
20920 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
20930 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
20940 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
20950 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
20960 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
20970 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
20980 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
20990 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
209a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
209b0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
209c0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
209d0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
209e0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
209f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
20a00 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
20a10 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
20a20 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
20a30 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
20a40 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
20a50 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
20a60 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
20a70 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
20a80 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
20a90 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
20aa0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
20ab0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
20ac0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
20ad0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20ae0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
20af0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
20b00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
20b10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20b20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
20b30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
20b40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
20b50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
20b60 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
20b70 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
20b80 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
20b90 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
20ba0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
20bb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
20bc0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
20bd0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
20be0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
20bf0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
20c00 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
20c10 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
20c20 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20c30 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
20c40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
20c50 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
20c60 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
20c70 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
20c80 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
20c90 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
20ca0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
20cb0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
20cc0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
20cd0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
20ce0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
20cf0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
20d00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
20d10 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
20d20 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
20d30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20d40 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
20d50 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
20d60 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
20d70 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
20d80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
20d90 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
20da0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
20db0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
20dc0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
20dd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
20de0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20df0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
20e00 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
20e10 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
20e20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
20e30 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
20e40 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
20e50 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
20e60 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
20e70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
20e80 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
20e90 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
20ea0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
20eb0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
20ec0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
20ed0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
20ee0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
20ef0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
20f00 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
20f10 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
20f20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
20f30 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
20f40 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
20f50 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
20f60 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
20f70 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
20f80 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
20f90 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
20fa0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
20fb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
20fc0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
20fd0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
20fe0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
20ff0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
21000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21010 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
21020 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
21030 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
21040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
21050 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
21060 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
21070 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
21080 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
21090 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
210a0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
210b0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
210c0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
210d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
210e0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
210f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21100 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
21110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21120 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
21130 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
21140 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
21150 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
21160 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
21170 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
21180 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
21190 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
211a0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
211b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
211c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
211d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
211e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
211f0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
21200 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
21210 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
21220 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
21230 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
21240 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
21250 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
21260 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
21270 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
21280 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
21290 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
212a0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
212b0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
212c0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
212d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
212e0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
212f0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
21300 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
21310 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
21320 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
21330 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
21340 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
21350 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
21360 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
21370 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
21380 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
21390 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
213a0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
213b0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
213c0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
213d0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
213e0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
213f0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
21400 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
21410 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
21420 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
21430 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
21440 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
21450 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
21460 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
21470 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
21480 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
21490 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
214a0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
214b0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
214c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
214d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
214e0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
214f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
21500 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
21510 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
21520 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
21530 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
21540 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
21550 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
21560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
21570 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
21580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21590 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
215a0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
215b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
215c0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
215d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
215e0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
215f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
21600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21610 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
21620 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
21630 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
21640 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
21650 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
21660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21670 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
21680 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21690 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
216a0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
216b0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
216c0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
216d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
216e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
216f0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
21700 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
21710 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
21720 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
21730 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
21740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
21750 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
21760 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
21770 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
21780 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
21790 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
217a0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
217b0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
217c0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
217d0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
217e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
217f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
21800 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
21810 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21820 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
21830 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
21840 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
21850 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
21860 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
21870 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
21880 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
21890 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
218a0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
218b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
218c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
218d0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
218e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
218f0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
21900 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
21910 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
21920 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
21930 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
21940 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21950 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
21960 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
21970 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
21980 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
21990 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
219a0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
219b0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
219c0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
219d0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
219e0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
219f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
21a00 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
21a10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
21a20 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
21a30 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31  .** [H13803] [H1
21a40 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b  3806] [H13809] [
21a50 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d  H13812] [H13815]
21a60 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32   [H13818] [H1382
21a70 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b  1] [H13824].** [
21a80 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d  H13827] [H13830]
21a90 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
21aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21ab0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21ac0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
21ad0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
21ae0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
21af0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21b00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
21b10 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
21b20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
21b30 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
21b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
21b50 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
21b60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
21b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21b80 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
21b90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
21ba0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
21bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
21bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21bd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
21be0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
21bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21c00 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
21c10 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
21c20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21c30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
21c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21c50 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
21c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
21c70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21c80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
21c90 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
21ca0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
21cb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21cc0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
21cd0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
21ce0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
21cf0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
21d00 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13300} <S70300>
21d10 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
21d20 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
21d30 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
21d40 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
21d50 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
21d60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
21d70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
21d80 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
21d90 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
21da0 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
21db0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
21dc0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
21dd0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
21de0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
21df0 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
21e00 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
21e10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
21e20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
21e30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
21e40 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
21e50 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
21e60 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
21e70 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
21e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21e90 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
21ea0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
21eb0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
21ec0 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
21ed0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
21ee0 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
21ef0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
21f00 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
21f10 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
21f20 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
21f30 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70  rupt]..** Incomp
21f40 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
21f50 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
21f60 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
21f70 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
21f80 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
21f90 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
21fa0 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
21fb0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
21fc0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
21fd0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  BORT]..**.** Req
21fe0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
21ff0 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a  11302] [H11304].
22000 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
22010 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
22020 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
22030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22040 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
22050 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
22060 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30   {H13330} <S7030
22070 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
22080 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
22090 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
220a0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
220b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
220c0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
220d0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
220e0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
220f0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
22100 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
22110 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
22120 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
22130 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
22140 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
22150 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
22160 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
22170 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
22180 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
22190 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
221a0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
221b0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
221c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20  .**.** {H11332} 
221d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
221e0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
221f0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
22200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22210 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
22220 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
22230 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
22240 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ram..**.** {H113
22250 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
22260 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
22270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
22280 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
22290 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
222a0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
222b0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
222c0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
222d0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
222e0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
222f0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
22300 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
22310 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
22320 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
22330 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
22340 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
22350 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  K]..**.** {H1133
22360 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
22370 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
22380 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
22390 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
223a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
223b0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
223c0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
223d0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
223e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
223f0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
22400 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
22410 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48   code]..**.** {H
22420 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
22430 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
22440 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
22450 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
22460 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
22470 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
22480 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
22490 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
224a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
224b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
224c0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
224d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
224e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
224f0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
22500 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
22510 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16100} <S20200>
22520 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
22530 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
22540 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
22550 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
22560 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
22570 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
22580 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
22590 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
225a0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
225b0 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
225c0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
225d0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
225e0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
225f0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
22600 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
22610 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
22620 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
22630 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
22640 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
22650 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
22660 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
22670 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
22680 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
22690 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
226a0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
226b0 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
226c0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
226d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
226e0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
226f0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
22700 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
22710 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
22720 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
22730 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
22740 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
22750 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
22760 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
22770 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22780 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
22790 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
227a0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
227b0 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   If a single pro
227c0 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
227d0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
227e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
227f0 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
22800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
22810 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
22820 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
22830 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
22840 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
22850 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22860 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
22870 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
22880 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
22890 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
228a0 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  d.  The length o
228b0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
228c0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
228d0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
228e0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
228f0 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
22900 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
22910 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
22920 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
22930 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
22940 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
22950 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
22960 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
22970 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
22980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
22990 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
229a0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
229b0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
229c0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
229d0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
229e0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
229f0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
22a00 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
22a10 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
22a20 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
22a30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
22a40 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
22a50 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
22a60 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
22a70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
22a80 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
22a90 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
22aa0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
22ab0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
22ac0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
22ad0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
22ae0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
22af0 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
22b00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
22b10 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
22b20 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
22b30 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
22b40 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
22b50 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
22b60 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
22b70 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
22b80 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
22b90 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
22ba0 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
22bb0 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
22bc0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
22bd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
22be0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
22bf0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
22c00 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
22c10 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
22c20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
22c30 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
22c40 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
22c50 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
22c60 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
22c70 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
22c80 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
22c90 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
22ca0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
22cb0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
22cc0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
22cd0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
22ce0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
22cf0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
22d00 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
22d10 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
22d20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
22d30 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
22d40 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
22d50 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
22d60 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
22d70 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
22d80 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
22d90 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
22da0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
22db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22dc0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
22dd0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
22de0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
22df0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
22e00 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
22e10 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
22e20 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
22e30 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
22e40 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
22e50 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
22e60 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
22e70 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
22e80 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
22e90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
22ea0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
22eb0 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
22ec0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
22ed0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
22ee0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
22ef0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
22f00 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
22f10 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
22f20 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
22f30 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
22f40 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
22f50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
22f60 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
22f70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
22f80 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
22f90 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
22fa0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
22fb0 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
22fc0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
22fd0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
22fe0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
22ff0 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
23000 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61  hree function ca
23010 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49  llbacks..**.** I
23020 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
23030 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
23040 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
23050 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
23060 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
23070 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
23080 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
23090 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
230a0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
230b0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
230c0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
230d0 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65  codings.  SQLite
230e0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
230f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23100 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
23110 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
23120 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
23130 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
23140 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69  d.  A function i
23150 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
23160 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
23170 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
23180 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
23190 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
231a0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
231b0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
231c0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41  egative nArg.  A
231d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
231e0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
231f0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
23200 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
23210 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
23220 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
23230 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
23240 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
23250 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
23260 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69  t.  .** A functi
23270 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
23280 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
23290 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
232a0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
232b0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
232c0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
232d0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
232e0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
232f0 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
23300 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
23310 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20  .**.** Built-in 
23320 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
23330 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
23340 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
23350 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
23360 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
23370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23380 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ed function with
23390 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76   a given name ov
233a0 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62  errides all.** b
233b0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
233c0 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  s in the same [d
233d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
233e0 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d  on] with the sam
233f0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65  e name..** Subse
23400 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  quent applicatio
23410 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
23420 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
23430 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69  name only overri
23440 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70  de .** prior app
23450 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23460 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
23470 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74  are an exact mat
23480 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75  ch for the.** nu
23490 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
234a0 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64  rs and preferred
234b0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
234c0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
234d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
234e0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
234f0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
23500 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
23510 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
23520 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
23530 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
23540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23550 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
23560 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
23570 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
23580 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
23590 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
235a0 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  g..**.** Require
235b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30  ments:.** [H1610
235c0 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36  3] [H16106] [H16
235d0 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48  109] [H16112] [H
235e0 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20  16118] [H16121] 
235f0 5b 48 31 36 31 32 34 5d 20 5b 48 31 36 31 32 37  [H16124] [H16127
23600 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48  ].** [H16130] [H
23610 31 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20  16133] [H16136] 
23620 5b 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32  [H16139] [H16142
23630 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
23640 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23650 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
23660 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
23670 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
23680 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
23690 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
236a0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
236b0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
236c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
236d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
236e0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
236f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
23700 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23710 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
23720 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
23730 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
23740 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23750 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
23760 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
23770 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
23780 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
23790 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
237a0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
237b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
237c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
237d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
237e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
237f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
23800 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23810 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23820 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
23830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
23840 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
23850 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
23860 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53  ings {H10267} <S
23870 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a  50200> <H16100>.
23880 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
23890 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
238a0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
238b0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
238c0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
238d0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
238e0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
238f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23900 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
23910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23920 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
23930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23940 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
23950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
23960 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
23970 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
23980 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
23990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
239a0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
239b0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
239c0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
239d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
239e0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
239f0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
23a00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
23a10 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
23a20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
23a30 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
23a40 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
23a50 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
23a60 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
23a70 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
23a80 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
23a90 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
23aa0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
23ab0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
23ac0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
23ad0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
23ae0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
23af0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
23b00 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
23b10 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
23b20 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
23b30 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
23b40 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
23b50 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
23b60 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
23b70 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
23b80 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
23b90 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
23ba0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
23bb0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
23bc0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
23bd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
23be0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
23bf0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
23c00 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
23c10 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
23c20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
23c30 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23c40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
23c50 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
23c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
23c70 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
23c80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23c90 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
23ca0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
23cb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23cc0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
23cd0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
23ce0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
23cf0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
23d00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
23d10 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
23d20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
23d30 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
23d40 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
23d50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23d60 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
23d70 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
23d80 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30  r Values {H15100
23d90 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
23da0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
23db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
23dc0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
23dd0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
23de0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
23df0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
23e00 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
23e10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
23e20 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
23e30 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
23e40 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
23e50 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
23e60 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
23e70 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
23e80 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
23e90 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
23ea0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23eb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23ec0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23ed0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
23ee0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
23ef0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
23f00 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
23f10 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
23f20 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
23f30 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
23f40 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
23f50 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
23f60 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
23f70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23f80 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
23f90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
23fa0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
23fb0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
23fc0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
23fd0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
23fe0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
23ff0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
24000 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
24010 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24020 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
24030 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
24040 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
24050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24060 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
24070 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
24080 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
24090 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
240a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
240b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
240c0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
240d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
240e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
240f0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
24100 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
24110 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
24120 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
24130 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
24140 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
24150 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
24160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24170 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
24180 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
24190 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
241a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
241b0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
241c0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
241d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
241e0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
241f0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
24200 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
24210 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
24220 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
24230 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
24240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
24250 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
24260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
24270 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
24280 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
24290 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
242a0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
242b0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
242c0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
242d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
242e0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
242f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
24300 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
24310 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
24320 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
24330 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
24340 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
24350 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
24360 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
24370 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
24380 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
24390 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
243a0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
243b0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
243c0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
243d0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
243e0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
243f0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
24400 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
24410 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
24420 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
24430 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
24440 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
24450 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
24460 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
24470 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
24480 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
24490 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
244a0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
244b0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
244c0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
244d0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
244e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
244f0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
24500 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
24510 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
24520 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
24530 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
24540 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
24550 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
24560 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
24570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
24580 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
24590 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
245a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
245b0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
245c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
245d0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
245e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
245f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
24600 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
24610 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
24620 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
24630 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
24640 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
24650 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
24660 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
24670 20 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30   [H15103] [H1510
24680 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35  6] [H15109] [H15
24690 31 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48  112] [H15115] [H
246a0 31 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20  15118] [H15121] 
246b0 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35  [H15124].** [H15
246c0 31 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48  127] [H15130] [H
246d0 31 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a  15133] [H15136].
246e0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
246f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
24700 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
24710 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
24720 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
24730 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
24740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
24750 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
24760 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
24770 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
24780 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
24790 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
247a0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
247b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
247c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
247d0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
247e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
247f0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
24800 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
24810 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
24820 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
24830 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
24840 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
24850 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
24860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
24870 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
24880 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
24890 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
248a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
248b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
248c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
248d0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
248e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
248f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
24900 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
24910 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
24920 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24930 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
24940 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
24950 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
24960 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
24970 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
24980 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
24990 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
249a0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
249b0 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
249c0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
249d0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
249e0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
249f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
24a00 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
24a10 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
24a20 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
24a30 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
24a40 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
24a50 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
24a60 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
24a70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
24a80 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24a90 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
24aa0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
24ab0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
24ac0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
24ad0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
24ae0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
24af0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
24b00 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
24b10 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
24b20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
24b30 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
24b40 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
24b50 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
24b60 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
24b70 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
24b80 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
24b90 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
24ba0 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
24bb0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
24bc0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
24bd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
24be0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
24bf0 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
24c00 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
24c10 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
24c20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
24c30 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
24c40 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
24c50 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
24c60 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
24c70 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
24c80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
24c90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24ca0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
24cb0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
24cc0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
24cd0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
24ce0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
24cf0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
24d00 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
24d10 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32  * [H16211] [H162
24d20 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31  13] [H16215] [H1
24d30 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6217].*/.void *s
24d40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
24d50 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
24d60 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
24d70 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
24d80 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
24d90 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
24da0 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
24db0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
24dc0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
24dd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24de0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
24df0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
24e00 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
24e10 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
24e20 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
24e30 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
24e40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24e50 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
24e60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24e70 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
24e80 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
24e90 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
24ea0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
24eb0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
24ec0 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
24ed0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
24ee0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
24ef0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
24f00 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
24f10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
24f20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
24f30 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
24f40 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
24f50 2a 20 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f  * [H16243].*/.vo
24f60 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
24f70 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
24f80 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
24f90 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
24fa0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
24fb0 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
24fc0 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
24fd0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
24fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
24ff0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
25000 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
25010 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
25020 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
25030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25040 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
25050 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
25060 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
25070 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
25080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
25090 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
250a0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
250b0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
250c0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
250d0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
250e0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
250f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
25100 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73  ** [H16253].*/.s
25110 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
25120 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
25130 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
25140 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
25150 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
25160 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48  uxiliary Data {H
25170 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16270} <S20200>.
25180 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
25190 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
251a0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
251b0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
251c0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
251d0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
251e0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
251f0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
25200 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
25210 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
25220 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
25230 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
25240 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
25250 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
25260 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
25270 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
25280 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
25290 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
252a0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
252b0 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
252c0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
252d0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
252e0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
252f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
25300 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
25310 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
25320 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
25330 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
25340 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
25350 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
25360 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
25370 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
25380 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
25390 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
253a0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
253b0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
253c0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
253d0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
253e0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
253f0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
25400 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
25410 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
25420 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
25430 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
25440 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
25450 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
25460 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
25470 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
25480 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
25490 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
254a0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
254b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
254c0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
254d0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
254e0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
254f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25500 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66  ned function. If
25510 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
25520 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
25530 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
25540 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
25550 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
25560 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
25570 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
25580 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
25590 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
255a0 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
255b0 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
255c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
255d0 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
255e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
255f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
25600 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
25610 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
25620 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
25630 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
25640 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
25650 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
25660 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
25670 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
25680 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
25690 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
256a0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
256b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
256c0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
256d0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
256e0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
256f0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
25700 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
25710 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
25720 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
25730 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
25740 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
25750 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
25760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
25770 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
25780 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
25790 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
257a0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
257b0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
257c0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
257d0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
257e0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
257f0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
25800 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
25810 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
25820 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
25830 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
25840 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
25850 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
25860 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
25870 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
25880 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
25890 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
258a0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
258b0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
258c0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
258d0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
258e0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
258f0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
25900 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
25910 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
25920 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
25930 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
25940 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
25950 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
25960 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
25970 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25980 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
25990 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
259a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
259b0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
259c0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
259d0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
259e0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32  ents:.** [H16272
259f0 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32  ] [H16274] [H162
25a00 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31  76] [H16277] [H1
25a10 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a  6278] [H16279].*
25a20 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
25a30 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
25a40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
25a50 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
25a60 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
25a70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
25a80 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
25a90 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
25aa0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
25ab0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
25ac0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
25ad0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
25ae0 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31  r {H10280} <S301
25af0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
25b00 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
25b10 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
25b20 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
25b30 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
25b40 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
25b50 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
25b60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
25b70 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
25b80 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
25b90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
25ba0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
25bb0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
25bc0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
25bd0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
25be0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
25bf0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
25c00 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
25c10 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
25c20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
25c30 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
25c40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
25c50 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
25c60 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
25c70 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
25c80 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
25c90 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
25ca0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
25cb0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
25cc0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
25cd0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
25ce0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
25cf0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
25d00 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
25d10 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
25d20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
25d30 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
25d40 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
25d50 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
25d60 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
25d70 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
25d80 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
25d90 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
25da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
25db0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
25dc0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
25dd0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
25de0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
25df0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
25e00 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
25e10 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6400} <S20200>.*
25e20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25e30 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
25e40 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
25e50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
25e60 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
25e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
25e80 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
25e90 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
25ea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25eb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
25ec0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
25ed0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
25ee0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
25f00 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
25f10 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
25f20 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
25f30 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
25f40 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
25f50 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
25f60 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
25f70 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
25f80 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
25f90 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
25fa0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
25fb0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
25fc0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
25fd0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
25fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
25ff0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
26000 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
26010 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
26020 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26030 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
26040 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
26050 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
26060 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
26070 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
26080 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
26090 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
260a0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
260b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
260c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
260d0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
260e0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
260f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
26100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
26110 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
26120 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
26130 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
26140 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
26150 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
26160 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
26170 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
26180 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
26190 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
261a0 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
261b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
261c0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
261d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
261e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
261f0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
26200 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
26210 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
26220 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
26230 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26240 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
26250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26260 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
26270 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
26280 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
26290 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
262a0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
262b0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
262c0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
262d0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
262e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
262f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26300 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
26310 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26320 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
26330 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
26340 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20  essage.  SQLite 
26350 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
26360 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
26370 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
26380 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26390 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c  () as UTF-8. SQL
263a0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
263b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
263c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
263d0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
263e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
263f0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
26400 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
26410 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26420 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
26430 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
26440 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
26450 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
26460 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
26470 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
26480 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
26490 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
264a0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
264b0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
264c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
264d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
264e0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
264f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26500 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
26510 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
26520 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
26530 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
26540 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
26550 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26560 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
26570 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
26580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26590 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
265a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
265b0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
265c0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
265d0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
265e0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
265f0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
26600 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
26610 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
26620 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
26630 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
26640 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
26650 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
26660 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
26670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
26680 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
26690 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
266a0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
266b0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
266c0 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
266d0 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
266e0 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
266f0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
26700 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
26710 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
26720 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
26730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26740 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
26750 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
26760 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
26770 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
26780 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
26790 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
267a0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
267b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
267c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
267d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
267e0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
267f0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
26800 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
26810 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
26820 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
26830 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
26840 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
26850 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
26860 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
26870 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
26880 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
26890 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
268a0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
268b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
268c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
268d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
268e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
268f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
26900 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26910 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
26920 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
26930 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
26940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
26950 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
26960 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
26970 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
26980 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26990 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
269a0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
269b0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
269c0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
269d0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
269e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
269f0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
26a00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26a10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
26a20 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
26a30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26a40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
26a50 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
26a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26a70 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
26a80 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
26a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26aa0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
26ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26ac0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
26ad0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
26ae0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
26af0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26b00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26b10 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
26b20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
26b30 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
26b40 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
26b50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
26b60 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
26b70 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
26b80 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
26b90 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
26ba0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
26bb0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
26bc0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
26bd0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
26be0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
26bf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26c00 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
26c10 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  es..** If the 3r
26c20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
26c30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26c40 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
26c50 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
26c60 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
26c70 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
26c80 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
26c90 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
26ca0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
26cb0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
26cc0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
26cd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
26ce0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26cf0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
26d00 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
26d10 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
26d20 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
26d30 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
26d40 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
26d50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
26d60 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
26d70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26d80 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
26d90 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
26da0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
26db0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
26dc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
26dd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
26de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26df0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
26e00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
26e10 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
26e20 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
26e30 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
26e40 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
26e50 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
26e60 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
26e70 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
26e80 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
26e90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
26ea0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
26eb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
26ec0 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69  faces or.** sqli
26ed0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
26ee0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
26ef0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
26f00 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
26f10 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
26f20 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
26f30 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
26f40 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
26f50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
26f60 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63  copy the it or c
26f70 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
26f80 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
26f90 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
26fa0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
26fb0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
26fc0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
26fd0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26fe0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
26ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
27000 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
27010 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
27020 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
27030 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
27040 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
27050 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
27060 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
27070 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
27080 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
27090 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
270a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
270b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
270c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
270d0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
270e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
270f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
27100 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
27110 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
27120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27130 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
27140 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
27150 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
27160 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
27170 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
27180 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
27190 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
271a0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
271b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
271c0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
271d0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
271e0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
271f0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
27200 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
27210 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
27220 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
27230 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
27240 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27250 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
27260 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
27270 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
27280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
27290 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
272a0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
272b0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
272c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
272d0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
272e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
272f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
27300 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
27310 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
27320 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
27330 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
27340 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
27350 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27360 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27370 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
27380 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
27390 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
273a0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
273b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
273c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
273d0 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36  ** [H16403] [H16
273e0 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48  406] [H16409] [H
273f0 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20  16412] [H16415] 
27400 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31  [H16418] [H16421
27410 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48  ] [H16424].** [H
27420 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20  16427] [H16430] 
27430 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36  [H16433] [H16436
27440 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34  ] [H16439] [H164
27450 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31  42] [H16445] [H1
27460 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31  6448].** [H16451
27470 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34  ] [H16454] [H164
27480 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31  57] [H16460] [H1
27490 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71  6463].*/.void sq
274a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
274b0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
274c0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
274d0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
274e0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
274f0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
27500 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
27510 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
27520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27530 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
27540 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
27550 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
27560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27570 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
27580 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
27590 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
275a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
275b0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
275c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
275d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
275e0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
275f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27600 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
27610 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
27620 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
27630 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
27640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27650 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
27660 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
27670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27680 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
27690 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
276a0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
276b0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
276c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
276d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
276e0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
276f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27700 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
27710 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27730 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
27740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27750 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
27760 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27770 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27780 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
27790 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
277a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
277b0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
277c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
277d0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
277e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
277f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
27800 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
27810 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27820 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
27830 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
27840 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27850 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27860 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
27870 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
27880 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
27890 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
278a0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
278b0 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20  uences {H16600} 
278c0 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
278d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
278e0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
278f0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
27900 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
27910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27920 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
27930 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
27940 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
27950 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
27960 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
27970 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
27980 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
27990 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
279a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
279b0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
279c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
279d0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
279e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
279f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
27a00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
27a10 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
27a20 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
27a30 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
27a40 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
27a50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
27a60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
27a70 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
27a80 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
27a90 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
27aa0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
27ab0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
27ac0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
27ad0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
27ae0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
27af0 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
27b00 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
27b10 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
27b20 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
27b30 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
27b40 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
27b50 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
27b60 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
27b70 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
27b80 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
27b90 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f  SQLITE_UTF16] to
27ba0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74   indicate that t
27bb0 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78  he routine.** ex
27bc0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
27bd0 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69  o be UTF-16 stri
27be0 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ngs in the nativ
27bf0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72  e byte order, or
27c00 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
27c10 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f   can be [SQLITE_
27c20 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69  UTF16_ALIGNED] i
27c30 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75  f the.** the rou
27c40 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
27c50 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
27c60 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
27c70 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
27c80 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
27c90 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
27ca0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
27cb0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
27cc0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
27cd0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
27ce0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
27cf0 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
27d00 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
27d10 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
27d20 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
27d30 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
27d40 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
27d50 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
27d60 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
27d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
27d80 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
27d90 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
27da0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
27db0 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
27dc0 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
27dd0 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
27de0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
27df0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
27e00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27e10 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
27e20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27e30 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
27e40 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
27e50 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
27e60 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
27e70 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
27e80 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
27e90 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
27ea0 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
27eb0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
27ec0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
27ed0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
27ee0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
27ef0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
27f00 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
27f10 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
27f20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
27f30 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
27f40 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
27f50 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
27f60 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
27f70 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
27f80 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
27f90 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
27fa0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
27fb0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
27fc0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
27fd0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
27fe0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
27ff0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
28000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28010 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
28020 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
28030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28040 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
28050 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
28060 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
28070 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
28080 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
28090 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
280a0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
280b0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
280c0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
280d0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
280e0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
280f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28100 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
28110 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
28120 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28130 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
28140 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
28150 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
28160 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
28170 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
28180 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
28190 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
281a0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
281b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
281c0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
281d0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
281e0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
281f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
28200 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
28210 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
28220 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
28230 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
28240 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
28250 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b  s:.** [H16603] [
28260 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d  H16604] [H16606]
28270 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31   [H16609] [H1661
28280 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36  2] [H16615] [H16
28290 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a  618] [H16621].**
282a0 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32   [H16624] [H1662
282b0 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69  7] [H16630].*/.i
282c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
282d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
282e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
282f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
28300 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
28310 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
28320 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
28330 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
28340 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
28350 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
28360 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28370 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
28380 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
28390 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
283a0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
283b0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
283c0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
283d0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
283e0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
283f0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
28400 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
28410 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28420 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
28430 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
28440 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
28450 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
28460 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
28470 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
28480 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
28490 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
284a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
284b0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
284c0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37   Callbacks {H167
284d0 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
284e0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69  ** To avoid havi
284f0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
28500 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
28510 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
28520 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
28530 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
28540 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
28550 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
28560 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
28570 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
28580 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61  ection] to be ca
28590 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
285a0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
285b0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
285c0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
285d0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
285e0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
285f0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
28600 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28610 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
28620 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
28630 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
28640 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
28650 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
28660 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
28670 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36  d in UTF-8. {H16
28680 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
28690 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
286a0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
286b0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
286c0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
286d0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
286e0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
286f0 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
28700 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
28710 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
28720 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
28730 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
28740 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
28750 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
28760 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
28770 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
28780 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
28790 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
287a0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
287b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
287c0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
287d0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
287e0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
287f0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
28800 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
28810 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
28820 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
28830 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
28840 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
28850 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
28860 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
28870 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
28880 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
28890 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
288a0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
288b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
288c0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
288d0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
288e0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
288f0 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
28900 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
28910 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
28920 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
28930 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
28940 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28950 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
28960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28970 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
28980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
28990 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
289a0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  2()]..**.** Requ
289b0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
289c0 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b  6702] [H16704] [
289d0 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73  H16706].*/.int s
289e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
289f0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
28a00 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
28a10 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
28a20 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
28a30 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
28a40 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
28a50 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
28a60 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
28a70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
28a80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
28a90 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
28aa0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
28ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
28ac0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
28ad0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
28ae0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
28af0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
28b00 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
28b10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
28b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
28b30 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
28b40 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
28b50 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
28b60 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
28b70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
28b80 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
28b90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
28ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28bb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
28bc0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
28bd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
28be0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
28bf0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
28c00 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
28c10 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
28c20 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
28c30 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
28c40 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
28c50 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
28c60 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
28c70 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
28c80 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
28c90 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
28ca0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
28cb0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
28cc0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
28cd0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
28ce0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
28cf0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
28d00 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
28d10 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
28d20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
28d40 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
28d50 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
28d60 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
28d70 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
28d80 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
28d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28da0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
28db0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
28dc0 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53  Time {H10530} <S
28dd0 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40410>.**.** The
28de0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
28df0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
28e00 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
28e10 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
28e20 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
28e30 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
28e40 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
28e50 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
28e60 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
28e70 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
28e80 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
28e90 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
28ea0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
28eb0 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
28ec0 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
28ed0 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
28ee0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
28ef0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
28f00 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
28f10 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
28f20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
28f30 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
28f40 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
28f50 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
28f60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
28f70 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
28f80 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
28f90 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
28fa0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
28fb0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
28fc0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
28fd0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
28fe0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
28ff0 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d  H10533] [H10536]
29000 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29010 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
29020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
29030 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
29040 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
29050 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
29060 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
29070 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
29080 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
29090 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
290a0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
290b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
290c0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
290d0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
290e0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
290f0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
29100 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
29110 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
29120 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
29130 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
29140 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29150 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
29160 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
29170 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
29180 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
29190 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
291a0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
291b0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
291c0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
291d0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
291e0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
291f0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
29200 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
29210 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
29220 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
29230 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
29240 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
29250 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
29260 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
29270 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
29280 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
29290 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
292a0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
292b0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
292c0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
292d0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
292e0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
292f0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
29300 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
29310 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
29320 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
29330 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
29340 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
29350 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   The [temp_store
29360 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
29370 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
29380 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
29390 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
293a0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
293b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
293c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
293d0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
293e0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
293f0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
29400 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
29410 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
29420 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
29430 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
29440 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
29450 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
29460 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
29470 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
29480 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
29490 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
294a0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
294b0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
294c0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
294d0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
294e0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
294f0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
29500 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
29510 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
29520 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
29530 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
29540 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
29550 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
29560 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
29570 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
29580 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
29590 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
295a0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
295b0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
295c0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
295d0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
295e0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
295f0 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e  H12930} <S60200>
29600 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
29610 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
29620 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29630 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
29640 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
29650 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
29660 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
29670 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
29680 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
29690 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
296a0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
296b0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74  spectively.  Aut
296c0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
296d0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
296e0 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
296f0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
29700 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
29710 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
29720 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
29730 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
29740 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
29750 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
29760 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
29770 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
29780 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
29790 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
297a0 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
297b0 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
297c0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
297d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
297e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
297f0 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
29800 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
29810 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
29820 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
29830 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
29840 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
29850 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
29860 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
29870 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
29880 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
29890 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
298a0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
298b0 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
298c0 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
298d0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
298e0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
298f0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
29900 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
29910 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
29920 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
29930 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
29940 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
29950 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
29960 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
29970 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
29980 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d  ements: [H12931]
29990 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33   [H12932] [H1293
299a0 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69  3] [H12934].*/.i
299b0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
299c0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
299d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
299e0 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
299f0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
29a00 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
29a10 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20  tement {H13120} 
29a20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
29a30 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
29a40 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
29a50 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
29a60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29a70 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
29a80 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
29a90 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
29aa0 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61  gs.  The [databa
29ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
29ac0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
29ad0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
29ae0 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
29af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29b00 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  ] that was the f
29b10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
29b20 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
29b30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
29b40 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
29b50 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
29b60 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
29b70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29b80 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
29b90 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
29ba0 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a  ments: [H13123].
29bb0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
29bc0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
29bd0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
29bf0 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
29c00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29c10 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30  {H13140} <S60600
29c20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
29c30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29c50 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
29c60 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
29c70 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
29c80 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
29c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29ca0 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d  n] pDb.  If pStm
29cb0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
29cc0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
29cd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29ce0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
29cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29d00 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
29d10 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
29d20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
29d30 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72  b.  If no prepar
29d40 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
29d50 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
29d60 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
29d70 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
29d80 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
29d90 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
29da0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
29db0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
29dc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
29dd0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
29de0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
29df0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
29e00 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
29e10 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
29e20 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
29e30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52  pointer..**.** R
29e40 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
29e50 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b  3143] [H13146] [
29e60 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d  H13149] [H13152]
29e70 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
29e80 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
29e90 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
29ea0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
29eb0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
29ec0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
29ed0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
29ee0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
29ef0 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36  cks {H12950} <S6
29f00 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
29f10 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
29f20 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
29f30 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
29f40 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
29f50 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
29f60 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
29f70 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
29f80 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
29f90 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
29fa0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
29fb0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
29fc0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
29fd0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
29fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29ff0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2a000 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2a010 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2a020 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2a030 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2a040 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2a050 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2a060 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2a070 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
2a080 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
2a090 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
2a0a0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2a0b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2a0c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
2a0d0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2a0e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a0f0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2a100 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
2a110 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2a120 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2a130 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74  allback..** If t
2a140 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
2a150 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
2a160 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
2a170 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
2a180 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2a190 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2a1a0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
2a1b0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2a1c0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2a1d0 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2a1e0 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
2a1f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2a200 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2a210 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a220 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
2a230 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2a240 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2a250 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2a260 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2a270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2a280 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
2a290 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
2a2a0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2a2b0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2a2c0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2a2d0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2a2e0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2a2f0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2a300 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a310 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2a320 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
2a330 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
2a340 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
2a350 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
2a360 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2a370 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a380 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a390 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2a3a0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2a3b0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2a3c0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2a3d0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2a3e0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2a3f0 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
2a400 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
2a410 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
2a420 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
2a430 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2a440 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2a450 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2a460 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2a470 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2a480 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2a490 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 20  rmally.  If the 
2a4a0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2a4b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2a4c0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2a4d0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2a4e0 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2a4f0 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  ]..** The rollba
2a500 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
2a510 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
2a520 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
2a530 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
2a540 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
2a550 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
2a560 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
2a570 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
2a580 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
2a590 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2a5a0 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2a5b0 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2a5c0 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2a5d0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2a5e0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2a5f0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2a600 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2a610 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2a620 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2a630 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2a640 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2a650 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
2a660 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2a670 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2a680 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2a690 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2a6a0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2a6b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2a6c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2a6d0 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
2a6e0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2a6f0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2a700 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2a710 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
2a720 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
2a730 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
2a740 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
2a750 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
2a760 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
2a770 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2a780 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2a790 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2a7a0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2a7b0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d  nts:.** [H12951]
2a7c0 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35   [H12952] [H1295
2a7d0 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32  3] [H12954] [H12
2a7e0 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d  955].** [H12961]
2a7f0 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36   [H12962] [H1296
2a800 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76  3] [H12964].*/.v
2a810 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
2a820 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
2a830 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
2a840 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
2a850 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2a860 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2a870 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
2a880 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
2a890 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
2a8a0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
2a8b0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
2a8c0 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2970} <S60400>.*
2a8d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a8e0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
2a8f0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2a900 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
2a910 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
2a920 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2a930 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
2a940 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
2a950 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2a960 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2a970 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2a980 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2a990 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
2a9a0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2a9b0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2a9c0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
2a9d0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
2a9e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2a9f0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2aa00 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
2aa10 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2aa20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
2aa30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
2aa40 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
2aa50 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2aa60 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2aa70 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eted..** The fir
2aa80 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2aa90 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2aaa0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
2aab0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
2aac0 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
2aad0 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
2aae0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
2aaf0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2ab00 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
2ab10 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
2ab20 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
2ab30 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
2ab40 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
2ab50 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
2ab60 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
2ab70 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2ab80 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
2ab90 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2aba0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2abb0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2abc0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2abd0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
2abe0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2abf0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2ac00 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c  ow..** The final
2ac10 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
2ac20 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
2ac30 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
2ac40 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  * In the case of
2ac50 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2ac60 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2ac70 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2ac80 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2ac90 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2aca0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2acb0 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2acc0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2acd0 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2ace0 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2acf0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2ad00 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
2ad10 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2ad20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2ad30 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2ad40 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2ad50 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2ad60 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2ad70 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2ad80 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2ad90 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2ada0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2adb0 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2adc0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2add0 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2ade0 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2adf0 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2ae00 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2ae10 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2ae20 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2ae30 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2ae40 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2ae50 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2ae60 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2ae70 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2ae80 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2ae90 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2aea0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2aeb0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2aec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2aed0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2aee0 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2aef0 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2af00 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2af10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2af20 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2af30 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2af40 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2af50 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2af60 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2af70 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2af80 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2af90 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2afa0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2afb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2afc0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2afd0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2afe0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2aff0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2b000 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2b010 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2b020 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2b030 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2b040 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2b050 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
2b060 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2b070 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2b080 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b090 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2b0a0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2b0b0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2b0c0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2b0d0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2b0e0 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
2b0f0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37  ments:.** [H1297
2b100 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32  1] [H12973] [H12
2b110 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48  975] [H12977] [H
2b120 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20  12979] [H12981] 
2b130 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36  [H12983] [H12986
2b140 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
2b150 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
2b160 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2b170 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
2b180 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
2b190 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
2b1a0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
2b1b0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
2b1c0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2b1d0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
2b1e0 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48  d Pager Cache {H
2b1f0 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a  10330} <S30900>.
2b200 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2b210 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61  ared cache} {sha
2b220 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a  red cache mode}.
2b230 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b240 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
2b250 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
2b260 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
2b270 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
2b280 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
2b290 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
2b2a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b2b0 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
2b2c0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
2b2d0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
2b2e0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
2b2f0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2b300 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
2b310 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
2b320 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
2b330 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61  .**.** Cache sha
2b340 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2b350 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2b360 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2b370 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2b380 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2b390 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2b3a0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2b3b0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2b3c0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2b3d0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2b3e0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2b3f0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2b400 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20  **.** The cache 
2b410 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2b420 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2b430 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2b440 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2b450 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2b460 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2b470 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2b480 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2b490 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2b4a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b4b0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2b4c0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2b4d0 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2b4e0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2b4f0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2b500 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69  opened..**.** Vi
2b510 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
2b520 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68  not be used with
2b530 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e   a shared cache.
2b540 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
2b550 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
2b560 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
2b570 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
2b580 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
2b590 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
2b5a0 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
2b5b0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
2b5c0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
2b5d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b5e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
2b5f0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
2b600 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2b610 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
2b620 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
2b630 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2b640 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
2b650 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
2b660 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
2b670 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
2b680 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
2b690 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
2b6a0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
2b6b0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2b6c0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
2b6d0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
2b6e0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
2b6f0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
2b700 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
2b710 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
2b720 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a  ache Mode].**.**
2b730 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
2b740 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d  H10331] [H10336]
2b750 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33   [H10337] [H1033
2b760 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
2b770 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2b780 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2b790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
2b7a0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
2b7b0 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30  p Memory {H17340
2b7c0 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a  } <S30220>.**.**
2b7d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
2b7e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
2b7f0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2b800 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
2b810 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
2b820 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
2b830 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
2b840 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2b850 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
2b860 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
2b870 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
2b880 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ry used to cache
2b890 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
2b8a0 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
2b8b0 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
2b8c0 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65  example of non-e
2b8d0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e  ssential memory.
2b8e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  .** sqlite3_rele
2b8f0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2b900 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2b910 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2b920 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2b930 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2b940 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2b950 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2b960 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
2b970 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20  ments: [H17341] 
2b980 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20  [H17342].*/.int 
2b990 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2b9a0 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
2b9b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
2b9c0 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
2b9d0 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35  Heap Size {H1735
2b9e0 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a  0} <S30220>.**.*
2b9f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f  * The sqlite3_so
2ba00 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
2ba10 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
2ba20 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a   a "soft" limit.
2ba30 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  ** on the amount
2ba40 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2ba50 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
2ba60 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
2ba70 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e  .** If an intern
2ba80 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  al allocation is
2ba90 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20   requested that 
2baa0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2bab0 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69  .** soft heap li
2bac0 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
2bad0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
2bae0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  is invoked one o
2baf0 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20  r.** more times 
2bb00 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
2bb10 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
2bb20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70   allocation is p
2bb30 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
2bb40 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
2bb50 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61  led "soft", beca
2bb60 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  use if [sqlite3_
2bb70 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2bb80 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65  ].** cannot free
2bb90 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
2bba0 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
2bbb0 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
2bbc0 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
2bbd0 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
2bbe0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
2bbf0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
2bc00 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
2bc10 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
2bc20 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
2bc30 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
2bc40 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
2bc50 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
2bc60 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
2bc70 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2bc80 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
2bc90 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
2bca0 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
2bcb0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
2bcc0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
2bcd0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
2bce0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
2bcf0 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
2bd00 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
2bd10 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2bd20 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  it..** But if th
2bd30 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2bd40 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f  t cannot be hono
2bd50 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  red, execution w
2bd60 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
2bd70 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
2bd80 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20   notification.  
2bd90 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2bda0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2bdb0 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2bdc0 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2bdd0 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2bde0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2bdf0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2be00 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2be10 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2be20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2be30 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2be40 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2be50 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2be60 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2be70 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2be80 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2be90 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2bea0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2beb0 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2bec0 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2bed0 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2bee0 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2bef0 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2bf00 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2bf10 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2bf20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2bf30 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2bf40 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2bf50 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2bf60 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2bf70 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2bf80 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2bf90 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2bfa0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2bfb0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31  ents:.** [H16351
2bfc0 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 33  ] [H16352] [H163
2bfd0 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 31  53] [H16354] [H1
2bfe0 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a  6355] [H16358].*
2bff0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2c000 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2c010 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2c020 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2c030 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2c040 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2c050 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30   {H12850} <S6030
2c060 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
2c070 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
2c080 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
2c090 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
2c0a0 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
2c0b0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
2c0c0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
2c0d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c0e0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2c0f0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
2c100 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
2c110 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2c120 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69   The column is i
2c130 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2c140 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2c150 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2c160 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2c170 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
2c180 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2c190 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
2c1a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2c1b0 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
2c1c0 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
2c1d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2c1e0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2c1f0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2c200 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
2c210 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
2c220 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
2c230 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
2c240 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
2c250 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
2c260 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
2c270 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
2c280 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
2c290 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
2c2a0 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
2c2b0 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
2c2c0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2c2d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
2c2e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
2c2f0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
2c300 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
2c310 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
2c320 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
2c330 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
2c340 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
2c350 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
2c360 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20  .**.** Metadata 
2c370 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
2c380 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
2c390 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
2c3a0 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68  assed as the 5th
2c3b0 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65  .** and subseque
2c3c0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
2c3d0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
2c3e0 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
2c3f0 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
2c400 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
2c410 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
2c420 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
2c430 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
2c440 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  itted..**.** <bl
2c450 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2c460 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2c470 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
2c480 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
2c490 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
2c4a0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
2c4b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
2c4c0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2c4d0 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
2c4e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
2c4f0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2c500 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
2c510 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
2c520 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
2c530 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
2c540 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2c550 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
2c560 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
2c570 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
2c580 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
2c590 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2c5a0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
2c5b0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
2c5c0 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
2c5d0 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
2c5e0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2c5f0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
2c600 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
2c610 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2c620 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2c630 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69  * The memory poi
2c640 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2c650 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2c660 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2c670 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
2c680 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
2c690 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2c6a0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
2c6b0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
2c6c0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
2c6d0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
2c6e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
2c6f0 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
2c700 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
2c710 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2c720 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2c730 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
2c740 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2c750 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2c760 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2c770 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2c780 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2c790 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2c7a0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2c7b0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2c7c0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2c7d0 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2c7e0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2c7f0 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72   column. If ther
2c800 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
2c810 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
2c820 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2c830 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
2c840 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2c850 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2c860 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
2c870 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
2c880 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
2c890 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
2c8a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2c8b0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
2c8c0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
2c8d0 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
2c8e0 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
2c8f0 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
2c900 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
2c910 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
2c920 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
2c930 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
2c940 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
2c950 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
2c960 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
2c970 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
2c980 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
2c990 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
2c9a0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
2c9b0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2c9c0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2c9d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2c9e0 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
2c9f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ca00 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
2ca10 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
2ca20 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
2ca30 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
2ca40 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
2ca50 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2ca60 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2ca70 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2ca80 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2ca90 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2caa0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
2cab0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2cac0 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
2cad0 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
2cae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2caf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2cb00 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
2cb10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2cb20 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
2cb30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
2cb40 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
2cb50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
2cb60 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
2cb70 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
2cb80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
2cb90 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
2cba0 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
2cbb0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
2cbc0 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
2cbd0 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
2cbe0 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
2cbf0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
2cc00 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
2cc10 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
2cc20 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
2cc30 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
2cc40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2cc50 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2cc60 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2cc70 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
2cc80 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
2cc90 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
2cca0 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
2ccb0 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
2ccc0 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
2ccd0 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
2cce0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2ccf0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2cd00 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
2cd10 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2cd20 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
2cd30 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d  tension {H12600}
2cd40 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20500>.**.** 
2cd50 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c  This interface l
2cd60 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65  oads an SQLite e
2cd70 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2cd80 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20   from the named 
2cd90 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  file..**.** {H12
2cda0 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  601} The sqlite3
2cdb0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2cdc0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2cdd0 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2cde0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
2cdf0 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
2ce00 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
2ce10 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
2ce20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d  ..**.** {H12602}
2ce30 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   The entry point
2ce40 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a   is zProc..**.**
2ce50 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20   {H12603} zProc 
2ce60 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69  may be 0, in whi
2ce70 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65  ch case the name
2ce80 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f   of the entry po
2ce90 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  int.**          
2cea0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
2ceb0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
2cec0 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nit"..**.** {H12
2ced0 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33  604} The sqlite3
2cee0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2cef0 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ) interface shal
2cf00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
2cf10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
2cf20 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
2cf30 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2cf40 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
2cf50 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48   wrong..**.** {H
2cf60 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72  12605} If an err
2cf70 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
2cf80 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
2cf90 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
2cfa0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c        [sqlite3_l
2cfb0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2cfc0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2cfd0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20   attempt to.**  
2cfe0 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a          fill *pz
2cff0 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
2d000 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
2d010 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
2d020 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61  **          obta
2d030 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2d040 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45  e3_malloc()]. {E
2d050 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  ND}  The calling
2d060 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2d070 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65        should fre
2d080 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
2d090 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d0a0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2d0b0 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73   {H12606} Extens
2d0c0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
2d0d0 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
2d0e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2d0f0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2d100 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2d110 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
2d120 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20   this API,.**   
2d130 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73 65         otherwise
2d140 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
2d150 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  e returned..*/.i
2d160 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
2d170 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
2d180 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2d190 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
2d1a0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
2d1b0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
2d1c0 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
2d1d0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
2d1e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2d1f0 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
2d200 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
2d210 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
2d220 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
2d230 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
2d240 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
2d250 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
2d260 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
2d270 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
2d280 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
2d290 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
2d2a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2d2b0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2d2c0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2d2d0 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35  g {H12620} <S205
2d2e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  00>.**.** So as 
2d2f0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
2d300 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
2d310 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
2d320 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
2d330 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
2d340 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
2d350 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
2d360 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
2d370 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
2d380 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
2d390 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
2d3a0 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
2d3b0 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
2d3c0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2d3d0 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
2d3e0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2d3f0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
2d400 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
2d410 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2d420 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
2d430 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
2d440 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  #1863..**.** {H1
2d450 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73  2621} Call the s
2d460 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2d470 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
2d480 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
2d490 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20  f==1.**         
2d4a0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
2d4b0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
2d4c0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
2d4d0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
2d4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 62  **          it b
2d4f0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
2d500 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78  *.** {H12622} Ex
2d510 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2d520 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
2d530 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2d540 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2d550 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
2d560 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
2d570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d580 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
2d590 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
2d5a0 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30  ns {H12640} <S20
2d5b0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2d5c0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
2d5d0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
2d5e0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
2d5f0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
2d600 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
2d610 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
2d620 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
2d630 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
2d640 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74   to all new [dat
2d650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d660 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  s]. {END}.**.** 
2d670 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
2d680 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
2d690 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2d6a0 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20  n an array that 
2d6b0 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  is.** obtained f
2d6c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2d6d0 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20  loc()].  If you 
2d6e0 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
2d6f0 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20  k checker.** on 
2d700 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
2d710 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
2d720 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
2d730 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65  is array, invoke
2d740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d750 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2d760 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68  n()] prior to sh
2d770 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74  utdown to free t
2d780 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a  he memory..**.**
2d790 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 66   {H12641} This f
2d7a0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
2d7b0 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  s an extension e
2d7c0 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
2d7d0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  is.**          a
2d7e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2d7f0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2d800 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
2d810 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  nnection].**    
2d820 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20        is opened 
2d830 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
2d840 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2d850 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
2d860 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2d870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
2d880 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44  **.** {H12642} D
2d890 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
2d8a0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
2d8b0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
2d8c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
2d8d0 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69       multiple ti
2d8e0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2d8f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
2d900 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  armless..**.** {
2d910 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75  H12643} This rou
2d920 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
2d930 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
2d940 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
2d950 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ay.**          t
2d960 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
2d970 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d980 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lloc()]..**.** {
2d990 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69  H12644} Automati
2d9a0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70  c extensions app
2d9b0 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68  ly across all th
2d9c0 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  reads..*/.int sq
2d9d0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
2d9e0 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74  sion(void (*xEnt
2d9f0 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b  ryPoint)(void));
2da00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2da10 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
2da20 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
2da30 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32  ing {H12660} <S2
2da40 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2da50 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2da60 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  es all previousl
2da70 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74  y registered aut
2da80 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73  omatic.** extens
2da90 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20  ions. {END}  It 
2daa0 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
2dab0 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a  t of all prior.*
2dac0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  * [sqlite3_auto_
2dad0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c  extension()] cal
2dae0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36  ls..**.** {H1266
2daf0 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  1} This function
2db00 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
2db10 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2db20 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
2db30 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
2db40 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ions..**.** {H12
2db50 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69  662} This functi
2db60 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
2db70 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2db80 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
2db90 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2dba0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
2dbb0 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
2dbc0 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
2dbd0 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
2dbe0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
2dbf0 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
2dc00 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65  ******.**.** The
2dc10 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
2dc20 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2dc30 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
2dc40 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
2dc50 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
2dc60 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
2dc70 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
2dc80 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
2dc90 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
2dca0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
2dcb0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
2dcc0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
2dcd0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
2dce0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
2dcf0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2dd00 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
2dd10 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
2dd20 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
2dd30 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
2dd40 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
2dd50 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
2dd60 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
2dd70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
2dd80 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
2dd90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
2dda0 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
2ddb0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2ddc0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
2ddd0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
2dde0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2ddf0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
2de00 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
2de10 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2de20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
2de30 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2de40 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
2de50 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
2de60 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
2de70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2de80 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
2de90 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d   Object {H18000}
2dea0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2deb0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
2dec0 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
2ded0 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20  able module}.** 
2dee0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2def0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
2df00 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
2df10 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
2df20 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
2df30 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
2df40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2df50 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
2df60 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
2df70 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
2df80 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
2df90 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
2dfa0 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ule..**.** A vir
2dfb0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2dfc0 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
2dfd0 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
2dfe0 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
2dff0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
2e000 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
2e010 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
2e020 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
2e030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2e040 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
2e050 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e060 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
2e070 20 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f   The registratio
2e080 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
2e090 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
2e0a0 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
2e0b0 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
2e0c0 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
2e0d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e0e0 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
2e0f0 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
2e100 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
2e110 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
2e120 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
2e130 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
2e140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e150 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
2e160 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
2e170 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
2e180 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
2e190 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
2e1a0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
2e1b0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
2e1c0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
2e1d0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
2e1e0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2e1f0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
2e200 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
2e210 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
2e220 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
2e230 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2e240 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
2e250 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
2e260 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
2e270 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
2e280 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
2e290 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
2e2a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2e2b0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
2e2c0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
2e2d0 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
2e2e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2e2f0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2e300 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
2e310 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2e320 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
2e330 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2e340 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
2e350 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
2e360 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
2e370 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
2e380 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2e390 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
2e3a0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2e3b0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
2e3c0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
2e3d0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e3e0 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
2e3f0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
2e400 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
2e410 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2e420 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2e430 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
2e440 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2e450 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
2e460 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2e470 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
2e480 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
2e490 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
2e4a0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2e4b0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2e4c0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
2e4d0 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
2e4e0 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
2e4f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2e500 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2e510 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
2e520 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
2e530 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2e540 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
2e550 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2e560 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
2e570 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2e580 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2e590 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
2e5a0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2e5b0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
2e5c0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
2e5d0 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
2e5e0 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
2e5f0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
2e600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e610 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
2e620 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e630 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2e640 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
2e650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2e660 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
2e670 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
2e680 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
2e690 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
2e6a0 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
2e6b0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2e6c0 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
2e6d0 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31   Information {H1
2e6e0 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8100} <S20400>.*
2e6f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2e700 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
2e710 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2e720 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2e730 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
2e740 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
2e750 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
2e760 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
2e770 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
2e780 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
2e790 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
2e7a0 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
2e7b0 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
2e7c0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2e7d0 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
2e7e0 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
2e7f0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
2e800 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
2e810 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
2e820 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
2e830 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
2e840 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
2e850 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
2e860 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f  s..**.** The aCo
2e870 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
2e880 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
2e890 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
2e8a0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
2e8b0 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
2e8c0 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
2e8d0 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
2e8e0 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
2e8f0 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
2e900 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72    The particular
2e910 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
2e920 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
2e930 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65  raint[].op.  The
2e940 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2e950 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
2e960 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74  n.** aConstraint
2e970 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f  [].iColumn.  aCo
2e980 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
2e990 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
2e9a0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
2e9b0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
2e9c0 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
2e9d0 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
2e9e0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
2e9f0 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
2ea00 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a  e if it cannot..
2ea10 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69  **.** The optimi
2ea20 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
2ea30 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
2ea40 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
2ea50 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
2ea60 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
2ea70 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
2ea80 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
2ea90 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
2eaa0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
2eab0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
2eac0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
2ead0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
2eae0 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
2eaf0 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
2eb00 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
2eb10 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
2eb20 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  se terms in the 
2eb30 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20  correct.** form 
2eb40 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68  that refer to th
2eb50 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
2eb60 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
2eb70 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
2eb80 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  Information abou
2eb90 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  t the ORDER BY c
2eba0 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20  lause is stored 
2ebb0 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a  in aOrderBy[]..*
2ebc0 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61  * Each term of a
2ebd0 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
2ebe0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
2ebf0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
2ec00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
2ec10 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
2ec20 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
2ec30 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
2ec40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2ec50 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
2ec60 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
2ec70 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72   xFilter.  If ar
2ec80 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
2ec90 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
2eca0 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
2ecb0 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
2ecc0 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
2ecd0 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
2ece0 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
2ecf0 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
2ed00 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72  rgv.  If aConstr
2ed10 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
2ed20 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
2ed30 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
2ed40 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
2ed50 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
2ed60 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
2ed70 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
2ed80 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
2ed90 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
2eda0 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  * The idxNum and
2edb0 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
2edc0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
2edd0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
2ede0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
2edf0 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hod..** [sqlite3
2ee00 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
2ee10 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
2ee20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a  if and only iff.
2ee30 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
2ee40 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
2ee50 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
2ee60 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
2ee70 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
2ee80 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
2ee90 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
2eea0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
2eeb0 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
2eec0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2eed0 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
2eee0 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
2eef0 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
2ef00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74  d..**.** The est
2ef10 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
2ef20 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
2ef30 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
2ef40 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
2ef50 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
2ef60 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
2ef70 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
2ef80 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
2ef90 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
2efa0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
2efb0 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
2efc0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
2efd0 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
2efe0 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
2eff0 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
2f000 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2f010 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
2f020 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
2f030 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
2f040 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
2f050 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
2f060 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
2f070 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2f080 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
2f090 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
2f0a0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
2f0b0 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
2f0c0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
2f0d0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
2f0e0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
2f0f0 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
2f100 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
2f110 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
2f120 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
2f130 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
2f140 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
2f150 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
2f160 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
2f170 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
2f180 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
2f190 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
2f1a0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
2f1b0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
2f1c0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
2f1d0 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
2f1e0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
2f1f0 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
2f200 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f210 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
2f220 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
2f230 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
2f240 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2f250 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
2f260 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
2f270 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
2f280 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
2f290 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
2f2a0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
2f2b0 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
2f2c0 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
2f2d0 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
2f2e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2f2f0 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
2f300 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
2f310 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
2f320 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2f330 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
2f340 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
2f350 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
2f360 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
2f370 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
2f380 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
2f390 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
2f3a0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
2f3b0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
2f3c0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
2f3d0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
2f3e0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
2f3f0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
2f400 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
2f410 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
2f420 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
2f430 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
2f440 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
2f450 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
2f460 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
2f470 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
2f480 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
2f490 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
2f4a0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
2f4b0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
2f4c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
2f4d0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
2f4e0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
2f4f0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
2f500 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
2f510 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
2f520 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
2f530 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
2f540 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
2f550 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
2f560 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
2f570 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2f580 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
2f590 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2f5a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
2f5b0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2f5c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2f5d0 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
2f5e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2f5f0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
2f600 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
2f610 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2f620 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
2f630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2f640 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
2f650 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
2f660 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
2f670 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
2f680 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
2f690 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30   {H18200} <S2040
2f6a0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
2f6b0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  AL.**.** This ro
2f6c0 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
2f6d0 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
2f6e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2f6f0 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20  odule] name..** 
2f700 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
2f710 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
2f720 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
2f730 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
2f740 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
2f750 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65  he module, or be
2f760 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
2f770 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
2f780 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
2f790 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
2f7a0 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d  * The module nam
2f7b0 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
2f7c0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
2f7d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
2f7e0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
2f7f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f800 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  .  The name of t
2f810 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76  he module is giv
2f820 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65  en by the .** se
2f830 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
2f840 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2f850 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
2f860 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  r to.** the impl
2f870 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2f880 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
2f890 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20   module].   The 
2f8a0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
2f8b0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2f8c0 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ary client data 
2f8d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
2f8e0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
2f8f0 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65  * into the [xCre
2f900 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
2f910 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ct] methods of t
2f920 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2f930 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20   module.** when 
2f940 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  a new virtual ta
2f950 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20  ble is be being 
2f960 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69  created or reini
2f970 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  tialized..**.** 
2f980 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 68  This interface h
2f990 61 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  as exactly the s
2f9a0 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 63 61  ame effect as ca
2f9b0 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  lling.** [sqlite
2f9c0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
2f9d0 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c  v2()] with a NUL
2f9e0 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65  L client data de
2f9f0 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c  structor..*/.SQL
2fa00 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
2fa10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2fa20 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
2fa30 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fa40 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
2fa50 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
2fa60 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
2fa70 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
2fa80 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
2fa90 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
2faa0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
2fab0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
2fac0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
2fad0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2fae0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
2faf0 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
2fb00 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
2fb10 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
2fb20 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
2fb30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fb40 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
2fb50 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
2fb60 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30  entation {H18210
2fb70 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
2fb80 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2fb90 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
2fba0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68   identical to th
2fbb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2fbc0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68  e_module()] meth
2fbd0 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  od,.** except th
2fbe0 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 78 74  at it has an ext
2fbf0 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ra parameter to 
2fc00 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 65  specify .** a de
2fc10 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
2fc20 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e 74  n for the client
2fc30 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20   data pointer.  
2fc40 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
2fc50 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2fc60 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
2fc70 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2fc80 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
2fc90 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
2fca0 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
2fcb0 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53   pointer.  .*/.S
2fcc0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
2fcd0 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
2fce0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
2fcf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2fd00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2fd10 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
2fd20 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
2fd30 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
2fd40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2fd50 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
2fd60 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
2fd70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
2fd80 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
2fd90 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
2fda0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
2fdb0 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
2fdc0 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a,         /* Cl
2fdd0 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
2fde0 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
2fdf0 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
2fe00 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
2fe10 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
2fe20 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
2fe30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fe40 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2fe50 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
2fe60 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34  t {H18010} <S204
2fe70 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2fe80 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a   sqlite3_vtab.**
2fe90 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2fea0 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
2feb0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
2fec0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fed0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a  uses a subclass.
2fee0 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ** of the follow
2fef0 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
2ff00 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
2ff10 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
2ff20 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
2ff30 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
2ff40 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
2ff50 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
2ff60 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
2ff70 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
2ff80 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ff90 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
2ffa0 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
2ffb0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
2ffc0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
2ffd0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
2ffe0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
2fff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30000 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  ..**.** Virtual 
30010 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
30020 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
30030 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
30040 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
30050 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
30060 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
30070 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
30080 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
30090 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
300a0 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
300b0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
300c0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
300d0 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
300e0 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
300f0 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
30100 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65  o zErrMsg.  Afte
30110 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
30120 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
30130 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
30140 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
30150 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
30160 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
30170 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
30180 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
30190 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
301a0 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
301b0 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
301c0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
301d0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
301e0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
301f0 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
30200 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
30210 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
30220 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
30230 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
30240 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
30250 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
30260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30270 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
30280 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
30290 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
302a0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
302b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
302c0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
302d0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
302e0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
302f0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
30300 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
30310 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d  Object  {H18020}
30320 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
30330 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
30340 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
30350 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
30360 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
30370 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  L.**.** Every [v
30380 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30390 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
303a0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
303b0 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
303c0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
303d0 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
303e0 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
303f0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
30400 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
30410 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
30420 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
30430 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
30440 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
30450 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
30460 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
30470 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
30480 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
30490 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
304a0 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
304b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
304c0 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
304d0 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73  e] method.  Cuss
304e0 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
304f0 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
30500 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
30510 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
30520 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
30530 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
30540 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
30550 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30560 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
30570 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
30580 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
30590 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
305a0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
305b0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
305c0 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
305d0 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
305e0 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
305f0 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
30600 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
30610 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
30620 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
30630 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
30640 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
30650 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
30660 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
30670 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
30680 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
30690 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
306a0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
306b0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
306c0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
306d0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
306e0 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
306f0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31  irtual Table {H1
30700 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8280} <S20400>.*
30710 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
30720 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74  *.** The [xCreat
30730 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
30740 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
30750 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
30760 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
30770 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
30780 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
30790 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
307a0 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
307b0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
307c0 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
307d0 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
307e0 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  lement..*/.SQLIT
307f0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
30800 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
30810 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
30820 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
30830 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
30840 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
30850 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
30860 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48  Virtual Table {H
30870 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18300} <S20400>.
30880 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
30890 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
308a0 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
308b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
308c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
308d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
308e0 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
308f0 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
30900 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
30910 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
30920 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
30930 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
30940 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
30950 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
30960 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
30970 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
30980 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
30990 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
309a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
309b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
309c0 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
309d0 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
309e0 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
309f0 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
30a00 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
30a10 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
30a20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
30a30 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
30a40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
30a50 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
30a60 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
30a70 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
30a80 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
30a90 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
30aa0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
30ab0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
30ac0 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
30ad0 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
30ae0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
30af0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
30b00 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
30b10 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
30b20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
30b30 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
30b40 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
30b50 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
30b60 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
30b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
30b80 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
30b90 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
30ba0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
30bb0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
30bc0 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
30bd0 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
30be0 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
30bf0 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
30c00 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
30c10 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
30c20 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
30c30 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
30c40 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
30c50 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
30c60 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
30c70 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
30c80 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
30c90 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
30ca0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
30cb0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30cc0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30cd0 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
30ce0 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
30cf0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
30d00 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
30d10 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
30d20 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
30d30 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
30d40 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
30d50 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
30d60 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
30d70 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
30d80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
30d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
30da0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
30db0 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d  en BLOB {H17800}
30dc0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59   <S30230>.** KEY
30dd0 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
30de0 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
30df0 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
30e00 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
30e10 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
30e20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
30e30 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
30e40 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
30e50 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
30e60 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
30e70 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73  rmed..** Objects
30e80 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
30e90 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
30ea0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
30eb0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
30ec0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
30ed0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
30ee0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
30ef0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
30f00 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
30f10 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
30f20 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
30f30 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
30f40 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
30f50 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
30f60 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
30f70 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
30f80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30f90 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
30fa0 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a   BLOB in bytes..
30fb0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
30fc0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
30fd0 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
30fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
30ff0 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
31000 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48  cremental I/O {H
31010 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17810} <S30230>.
31020 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
31030 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
31040 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
31050 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
31060 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
31070 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
31080 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
31090 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
310a0 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
310b0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
310c0 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
310d0 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
310e0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
310f0 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
31100 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
31110 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
31120 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
31130 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
31140 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
31150 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
31160 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42 4c 4f  ero, the the BLO
31170 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
31180 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
31190 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20  e access. If it 
311a0 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
311b0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
311c0 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  read access..**.
311d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
311e0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
311f0 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
31200 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
31210 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
31220 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
31230 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
31240 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
31250 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65  at.** is assigne
31260 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
31270 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64  ase is connected
31280 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e   using [ATTACH].
31290 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e  .** For the main
312a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
312b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
312c0 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20  e is "main"..** 
312d0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
312e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
312f0 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
31300 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
31310 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
31320 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
31330 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
31340 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
31350 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
31360 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
31370 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
31380 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73  d and *ppBlob is
31390 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20   set.** to be a 
313a0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  null pointer..**
313b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   This function s
313c0 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
313d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
313e0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
313f0 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
31400 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
31410 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
31420 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
31430 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
31440 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74   functions.  Not
31450 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
31460 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
31470 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
31480 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
31490 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
314a0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
314b0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
314c0 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
314d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
314e0 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
314f0 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
31500 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tine..**.** If t
31510 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
31520 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
31530 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
31540 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
31550 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
31560 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
31570 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
31580 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
31590 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
315a0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
315b0 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
315c0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
315d0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
315e0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
315f0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
31600 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
31610 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
31620 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b  n..** Calls to [
31630 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
31640 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
31650 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
31660 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
31670 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
31680 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
31690 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
316a0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e  _ABORT]..** Chan
316b0 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
316c0 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
316d0 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
316e0 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
316f0 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78  llback by the ex
31700 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  piration of the 
31710 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e  BLOB.  Such chan
31720 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ges will eventua
31730 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66  lly.** commit if
31740 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
31750 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
31760 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
31770 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
31780 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
31790 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65  nterface to dete
317a0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f  rmine the size o
317b0 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20  f.** the opened 
317c0 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65 20  blob.  The size 
317d0 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f  of a blob may no
317e0 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  t be changed by 
317f0 74 68 69 73 0a 2a 2a 20 75 6e 64 65 72 66 61 63  this.** underfac
31800 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44  e.  Use the [UPD
31810 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  ATE] SQL command
31820 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73   to change the s
31830 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62  ize of a.** blob
31840 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ..**.** The [sql
31850 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
31860 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ob()] and [sqlit
31870 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
31880 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ob()] interfaces
31890 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c  .** and the buil
318a0 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20  t-in [zeroblob] 
318b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  SQL function can
318c0 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73   be used, if des
318d0 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61  ired,.** to crea
318e0 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72  te an empty, zer
318f0 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e  o-filled blob in
31900 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f   which to read o
31910 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a  r write using.**
31920 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
31930 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
31940 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c  a resource leak,
31950 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f   every open [BLO
31960 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64  B handle] should
31970 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62   eventually.** b
31980 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20  e released by a 
31990 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
319a0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
319b0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
319c0 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20  ts:.** [H17813] 
319d0 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36  [H17814] [H17816
319e0 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38  ] [H17819] [H178
319f0 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a  21] [H17824].*/.
31a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
31a10 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
31a20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
31a30 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
31a40 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
31a50 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
31a60 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
31a70 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
31a80 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
31a90 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
31aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31ab0 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
31ac0 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c  andle {H17830} <
31ad0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c  S30230>.**.** Cl
31ae0 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  oses an open [BL
31af0 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  OB handle]..**.*
31b00 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42  * Closing a BLOB
31b10 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
31b20 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
31b30 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
31b40 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
31b50 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
31b60 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
31b70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
31b80 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
31b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
31ba0 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
31bb0 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79  mode]..** If any
31bc0 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
31bd0 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
31be0 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
31bf0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
31c00 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
31c10 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
31c20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
31c30 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
31c40 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
31c50 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
31c60 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
31c70 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
31c80 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
31c90 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
31ca0 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
31cb0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
31cc0 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
31cd0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
31ce0 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
31cf0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
31d00 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
31d10 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  rn value..**.** 
31d20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  The BLOB is clos
31d30 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c  ed unconditional
31d40 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69  ly.  Even if thi
31d50 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
31d60 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  s.** an error co
31d70 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  de, the BLOB is 
31d80 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a  still closed..**
31d90 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
31da0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
31db0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77 68  null pointer (wh
31dc0 69 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20  ich as would be 
31dd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66  returned.** by f
31de0 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
31df0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
31e00 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
31e10 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
31e20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
31e30 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38 33   [H17833] [H1783
31e40 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69  6] [H17839].*/.i
31e50 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
31e60 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
31e70 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
31e80 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
31e90 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
31ea0 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d  en BLOB {H17840}
31eb0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
31ec0 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  Returns the size
31ed0 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65   in bytes of the
31ee0 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65   BLOB accessible
31ef0 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63   via the .** suc
31f00 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64  cessfully opened
31f10 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
31f20 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d  n its only argum
31f30 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63  ent.  The.** inc
31f40 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f  remental blob I/
31f50 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f  O routines can o
31f60 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72  nly read or over
31f70 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67  writing existing
31f80 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74  .** blob content
31f90 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68  ; they cannot ch
31fa0 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
31fb0 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54   a blob..**.** T
31fc0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
31fd0 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
31fe0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
31ff0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
32000 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
32010 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
32020 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
32030 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
32040 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
32050 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
32060 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
32070 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
32080 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
32090 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
320a0 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
320b0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
320c0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
320d0 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
320e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
320f0 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a  .** [H17843].*/.
32100 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
32110 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
32120 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
32130 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
32140 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
32150 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31  ncrementally {H1
32160 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7850} <S30230>.*
32170 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
32180 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
32190 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
321a0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
321b0 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
321c0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
321d0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
321e0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
321f0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
32200 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
32210 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
32220 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
32230 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  .**.** If offset
32240 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
32250 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
32260 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
32270 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
32280 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
32290 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
322a0 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e  a is read.  If N
322b0 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
322c0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
322d0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
322e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
322f0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
32300 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
32310 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68   the blob (and h
32320 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
32330 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
32340 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
32350 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
32360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
32370 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
32380 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  face..**.** An a
32390 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66  ttempt to read f
323a0 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b  rom an expired [
323b0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
323c0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
323d0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
323e0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
323f0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51  * On success, SQ
32400 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
32410 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
32420 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
32430 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
32440 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
32450 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
32460 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
32470 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
32480 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
32490 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
324a0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
324b0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
324c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
324d0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
324e0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
324f0 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
32500 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
32510 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
32520 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
32530 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
32540 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
32550 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
32560 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
32570 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
32580 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32590 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
325a0 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  ite()]..**.** Re
325b0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
325c0 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d  H17853] [H17856]
325d0 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36   [H17859] [H1786
325e0 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37  2] [H17863] [H17
325f0 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f  865] [H17868].*/
32600 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
32610 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
32620 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
32630 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
32640 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
32650 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
32660 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
32670 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38  rementally {H178
32680 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  70} <S30230>.**.
32690 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
326a0 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74   is used to writ
326b0 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f  e data into an o
326c0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
326d0 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c  ] from a.** call
326e0 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
326f0 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
32700 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
32710 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
32720 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
32730 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
32740 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
32750 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
32760 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
32770 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
32780 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
32790 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
327a0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
327b0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
327c0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
327d0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
327e0 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
327f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
32800 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
32810 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
32820 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
32830 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
32840 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
32850 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
32860 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
32870 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
32880 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
32890 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69  ..** If offset i
328a0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
328b0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
328c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
328d0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
328e0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
328f0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
32900 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20  is written.  If 
32910 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
32920 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
32930 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
32940 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
32950 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
32960 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
32970 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
32980 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
32990 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
329a0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
329b0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
329c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
329d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
329e0 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74  .** An attempt t
329f0 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78  o write to an ex
32a00 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pired [BLOB hand
32a10 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61  le] fails with a
32a20 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
32a30 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
32a40 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  ].  Writes to th
32a50 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
32a60 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
32a70 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
32a80 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
32a90 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
32aa0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
32ab0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
32ac0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
32ad0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
32ae0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
32af0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
32b00 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
32b10 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
32b20 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
32b30 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
32b40 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
32b50 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  ts..**.** On suc
32b60 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
32b70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
32b80 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b  Otherwise, an  [
32b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
32ba0 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
32bb0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
32bc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
32bd0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
32be0 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
32bf0 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
32c00 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
32c10 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
32c20 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
32c30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
32c40 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
32c50 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
32c60 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
32c70 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
32c80 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
32c90 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
32ca0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
32cb0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
32cc0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
32cd0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
32ce0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53  ehavior..**.** S
32cf0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
32d00 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a  3_blob_read()]..
32d10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
32d20 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20  ts:.** [H17873] 
32d30 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35  [H17874] [H17875
32d40 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38  ] [H17876] [H178
32d50 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31  77] [H17879] [H1
32d60 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a  7882] [H17885].*
32d70 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e  * [H17888].*/.in
32d80 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
32d90 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
32da0 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
32db0 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
32dc0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
32dd0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
32de0 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
32df0 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c  jects {H11200} <
32e00 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20  S20100>.**.** A 
32e10 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
32e20 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
32e30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
32e40 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
32e50 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
32e60 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
32e70 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
32e80 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
32e90 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
32ea0 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
32eb0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
32ec0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
32ed0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
32ee0 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
32ef0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
32f00 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
32f10 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
32f20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
32f30 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
32f40 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
32f50 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
32f60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32f70 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65  _vfs_find() inte
32f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32f90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53  pointer to a VFS
32fa0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
32fb0 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61  .** Names are ca
32fc0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a  se sensitive..**
32fd0 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d   Names are zero-
32fe0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
32ff0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20   strings..** If 
33000 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
33010 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  h, a NULL pointe
33020 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
33030 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73  * If zVfsName is
33040 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
33050 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
33060 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65  turned..**.** Ne
33070 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
33080 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
33090 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
330a0 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20  ()..** Each new 
330b0 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20  VFS becomes the 
330c0 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74  default VFS if t
330d0 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
330e0 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   is set..** The 
330f0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
33100 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
33110 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
33120 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20  t injury..** To 
33130 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67  make an existing
33140 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65   VFS into the de
33150 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73  fault VFS, regis
33160 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20  ter it again.** 
33170 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c  with the makeDfl
33180 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20  t flag set.  If 
33190 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46  two different VF
331a0 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  Ses with the.** 
331b0 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65  same name are re
331c0 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65  gistered, the be
331d0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
331e0 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46  ned.  If a.** VF
331f0 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  S is registered 
33200 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74  with a name that
33210 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
33220 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20  mpty string,.** 
33230 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
33240 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
33250 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72  **.** Unregister
33260 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
33270 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
33280 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
33290 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65  ce..** If the de
332a0 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72  fault VFS is unr
332b0 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68  egistered, anoth
332c0 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e  er VFS is chosen
332d0 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   as.** the defau
332e0 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20  lt.  The choice 
332f0 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20  for the new VFS 
33300 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
33310 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
33320 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48  :.** [H11203] [H
33330 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20  11206] [H11209] 
33340 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35  [H11212] [H11215
33350 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71  ] [H11218].*/.sq
33360 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
33370 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
33380 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
33390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
333a0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
333b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
333c0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
333d0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
333e0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
333f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33400 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37  EF: Mutexes {H17
33410 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  000} <S20000>.**
33420 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
33430 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
33440 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
33450 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
33460 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68  ation. Though th
33470 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
33480 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
33490 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
334a0 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
334b0 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
334c0 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
334d0 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
334e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
334f0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
33500 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
33510 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
33520 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
33530 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
33540 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
33550 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
33560 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
33570 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
33580 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
33590 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
335a0 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
335b0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
335c0 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
335d0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
335e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
335f0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
33600 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
33610 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
33620 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
33630 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
33640 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
33650 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
33660 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
33670 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
33680 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
33690 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20   of routines.** 
336a0 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
336b0 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
336c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
336d0 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e   use in.** a sin
336e0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
336f0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
33700 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
33710 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
33720 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
33730 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
33740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
33750 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
33760 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
33770 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
33780 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53  dows..**.** If S
33790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
337a0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
337b0 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70  E_MUTEX_APPDEF p
337c0 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d  reprocessor.** m
337d0 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69  acro defined (wi
337e0 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54  th "-DSQLITE_MUT
337f0 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74  EX_APPDEF=1"), t
33800 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20  hen no mutex.** 
33810 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
33820 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  s included with 
33830 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20  the library. In 
33840 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a  this case the.**
33850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
33860 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f  t supply a custo
33870 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  m mutex implemen
33880 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65  tation using the
33890 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
338a0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
338b0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
338c0 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f  config() functio
338d0 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c  n.** before call
338e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ing sqlite3_init
338f0 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20  ialize() or any 
33900 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c  other public sql
33910 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f  ite3_.** functio
33920 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c  n that calls sql
33930 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
33940 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31  )..**.** {H17011
33950 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
33960 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74  tex_alloc() rout
33970 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  ine allocates a 
33980 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64  new.** mutex and
33990 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
339a0 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31  er to it. {H1701
339b0 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  2} If it returns
339c0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65   NULL.** that me
339d0 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78  ans that a mutex
339e0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c   could not be al
339f0 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33  located. {H17013
33a00 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  } SQLite.** will
33a10 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
33a20 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
33a30 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20  error. {H17014} 
33a40 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
33a50 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
33a60 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20  _alloc() is one 
33a70 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
33a80 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a   constants:.**.*
33a90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
33aa0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
33ab0 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  T.** <li>  SQLIT
33ac0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
33ad0 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
33ae0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
33af0 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53  ASTER.** <li>  S
33b00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
33b10 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_MEM.** <li>  
33b20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
33b30 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e  TIC_MEM2.** <li>
33b40 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
33b50 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c  TATIC_PRNG.** <l
33b60 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
33b70 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c  _STATIC_LRU.** <
33b80 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
33b90 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a  X_STATIC_LRU2.**
33ba0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31   </ul>.**.** {H1
33bb0 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20  7015} The first 
33bc0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  two constants ca
33bd0 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
33be0 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
33bf0 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
33c00 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74  ex.  The new mut
33c10 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20  ex is recursive 
33c20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
33c30 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69  X_RECURSIVE.** i
33c40 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e  s used but not n
33c50 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68  ecessarily so wh
33c60 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
33c70 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45  FAST is used. {E
33c80 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ND}.** The mutex
33c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33ca0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
33cb0 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
33cc0 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
33cd0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
33ce0 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
33cf0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
33d00 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
33d10 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d  nt to.  {H17016}
33d20 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c   But SQLite will
33d30 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20   only request a 
33d40 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20  recursive mutex 
33d50 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72  in.** cases wher
33d60 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64  e it really need
33d70 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66  s one.  {END} If
33d80 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
33d90 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
33da0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33db0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
33dc0 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
33dd0 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
33de0 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
33df0 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
33e00 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
33e10 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
33e20 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  FAST..**.** {H17
33e30 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61  017} The other a
33e40 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
33e50 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
33e60 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20  ex_alloc() each 
33e70 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
33e80 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
33e90 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
33ea0 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73  x. {END}  Four s
33eb0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
33ec0 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
33ed0 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
33ee0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
33ef0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
33f00 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
33f10 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
33f20 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
33f30 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
33f40 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
33f50 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
33f60 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
33f70 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
33f80 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
33f90 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
33fa0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
33fb0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
33fc0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
33fd0 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
33fe0 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
33ff0 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74  .** {H17018} Not
34000 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
34010 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
34020 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
34030 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
34040 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
34050 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
34060 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
34070 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
34080 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
34090 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
340a0 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b  n every call.  {
340b0 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20  H17034} But for 
340c0 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
340d0 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
340e0 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
340f0 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
34100 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
34110 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
34120 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  mber..**.** {H17
34130 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33  019} The sqlite3
34140 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
34150 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
34160 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
34170 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
34180 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30  mic mutex. {H170
34190 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61  20} SQLite is ca
341a0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
341b0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
341c0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
341d0 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41  it allocates. {A
341e0 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d  17021} The dynam
341f0 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
34200 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65  not be in.** use
34210 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
34220 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37  eallocated. {A17
34230 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20  022} Attempting 
34240 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
34250 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
34260 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34270 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b  ined behavior. {
34280 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e  H17023} SQLite n
34290 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
342a0 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
342b0 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ex. {END}.**.** 
342c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
342d0 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71  x_enter() and sq
342e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
342f0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  ) routines attem
34300 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61  pt.** to enter a
34310 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d   mutex. {H17024}
34320 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
34330 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
34340 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
34350 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
34360 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
34370 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
34380 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
34390 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
343a0 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d  E_BUSY. {H17025}
343b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
343c0 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
343d0 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
343e0 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
343f0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
34400 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65  .  {H17026} Mute
34410 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  xes created usin
34420 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  g.** SQLITE_MUTE
34430 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20  X_RECURSIVE can 
34440 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69  be entered multi
34450 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65  ple times by the
34460 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a   same thread..**
34470 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63   {H17027} In suc
34480 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
34490 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
344a0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
344b0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
344c0 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
344d0 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
344e0 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74  .  {A17028} If t
344f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
34500 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
34510 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
34520 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
34530 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
34540 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
34550 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20  ed..** {H17029} 
34560 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
34570 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
34580 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
34590 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
345a0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  exes..**.** Some
345b0 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
345c0 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
345d0 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
345e0 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
345f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
34600 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
34610 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
34620 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
34630 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
34640 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
34650 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
34660 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53    {H17030} The S
34670 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20  QLite core only 
34680 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c  ever uses.** sql
34690 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
346a0 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74   as an optimizat
346b0 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61  ion so this is a
346c0 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69  cceptable behavi
346d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33  or..**.** {H1703
346e0 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
346f0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
34700 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
34710 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
34720 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
34730 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
34740 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20  read.  {A17032} 
34750 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
34760 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
34770 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
34780 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
34790 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ed by the.** cal
347a0 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69  ling thread or i
347b0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
347c0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37  allocated.  {H17
347d0 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  033} SQLite will
347e0 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
347f0 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  her. {END}.**.**
34800 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   If the argument
34810 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
34820 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
34830 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
34840 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
34850 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
34860 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
34870 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
34880 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
34890 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
348a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
348b0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
348c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
348d0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
348e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
348f0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
34900 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
34910 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
34920 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
34930 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
34940 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
34950 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
34960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
34970 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
34980 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
34990 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
349a0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
349b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
349c0 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
349d0 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d   Object {H17120}
349e0 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50   <S20130>.** EXP
349f0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
34a00 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
34a10 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65  his structure de
34a20 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65  fines the low-le
34a30 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  vel routines.** 
34a40 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65  used to allocate
34a50 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73   and use mutexes
34a60 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c  ..**.** Usually,
34a70 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
34a80 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
34a90 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53  ns provided by S
34aa0 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66  QLite are.** suf
34ab0 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72  ficient, however
34ac0 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68   the user has th
34ad0 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73  e option of subs
34ae0 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f  tituting a custo
34af0 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  m.** implementat
34b00 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69  ion for speciali
34b10 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20  zed deployments 
34b20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77  or systems for w
34b30 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64  hich SQLite.** d
34b40 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
34b50 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
34b60 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68  mentation. In th
34b70 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65  is case, the use
34b80 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64  r.** creates and
34b90 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e   populates an in
34ba0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
34bb0 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73  tructure to pass
34bc0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
34bd0 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69  onfig() along wi
34be0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  th the [SQLITE_C
34bf0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
34c00 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ion..** Addition
34c10 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63  ally, an instanc
34c20 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
34c30 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
34c40 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20  as an.** output 
34c50 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75  variable when qu
34c60 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65  erying the syste
34c70 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  m for the curren
34c80 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  t mutex.** imple
34c90 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67  mentation, using
34ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
34cb0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70  FIG_GETMUTEX] op
34cc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
34cd0 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
34ce0 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
34cf0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
34d00 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
34d10 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74  t of system init
34d20 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68  ialization by th
34d30 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
34d40 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lize() function.
34d50 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65  .** {H17001} The
34d60 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74   xMutexInit rout
34d70 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c  ine shall be cal
34d80 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  led by SQLite on
34d90 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65  ce for each.** e
34da0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
34db0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
34dc0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  lize()]..**.** T
34dd0 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74  he xMutexEnd met
34de0 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
34df0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
34e00 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
34e10 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68  art of system sh
34e20 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71  utdown by the sq
34e30 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
34e40 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a   function. The.*
34e50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34e60 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
34e70 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72  is expected to r
34e80 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74  elease all outst
34e90 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72  anding.** resour
34ea0 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ces obtained by 
34eb0 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
34ec0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
34ed0 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20  , especially.** 
34ee0 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62  those obtained b
34ef0 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74  y the xMutexInit
34f00 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33   method. {H17003
34f10 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28  } The xMutexEnd(
34f20 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
34f30 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  hall be invoked 
34f40 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61  once for each ca
34f50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
34f60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a  hutdown()]..**.*
34f70 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
34f80 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65  seven methods de
34f90 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
34fa0 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41  ructure (xMutexA
34fb0 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46  lloc,.** xMutexF
34fc0 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72  ree, xMutexEnter
34fd0 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75  , xMutexTry, xMu
34fe0 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78  texLeave, xMutex
34ff0 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74  Held and.** xMut
35000 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65  exNotheld) imple
35010 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ment the followi
35020 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72  ng interfaces (r
35030 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a  espectively):.**
35040 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
35050 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
35060 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69  ex_alloc()] </li
35070 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
35080 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
35090 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
350a0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
350b0 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c  tex_enter()] </l
350c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
350d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
350e0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
350f0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
35100 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c  tex_leave()] </l
35110 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
35120 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
35130 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  d()] </li>.**   
35140 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
35150 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20  utex_notheld()] 
35160 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
35170 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69  *.** The only di
35180 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74  fference is that
35190 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69   the public sqli
351a0 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e  te3_XXX function
351b0 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20  s enumerated.** 
351c0 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69  above silently i
351d0 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61  gnore any invoca
351e0 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20  tions that pass 
351f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
35200 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76  nstead.** of a v
35210 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
35220 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  e. The implement
35230 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65  ations of the me
35240 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a  thods defined.**
35250 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
35260 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69  re are not requi
35270 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68  red to handle th
35280 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73  is case, the res
35290 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69  ults.** of passi
352a0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
352b0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76  r instead of a v
352c0 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
352d0 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a  e are undefined.
352e0 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61  ** (i.e. it is a
352f0 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f  cceptable to pro
35300 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  vide an implemen
35310 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66  tation that segf
35320 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69  aults if.** it i
35330 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20  s passed a NULL 
35340 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70  pointer)..*/.typ
35350 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
35360 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
35370 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  s sqlite3_mutex_
35380 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
35390 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
353a0 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a  thods {.  int (*
353b0 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64  xMutexInit)(void
353c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
353d0 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73  xEnd)(void);.  s
353e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a  qlite3_mutex *(*
353f0 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74  xMutexAlloc)(int
35400 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
35410 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f  exFree)(sqlite3_
35420 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
35430 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28   (*xMutexEnter)(
35440 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
35450 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
35460 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  Try)(sqlite3_mut
35470 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
35480 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c  xMutexLeave)(sql
35490 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
354a0 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c   int (*xMutexHel
354b0 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d)(sqlite3_mutex
354c0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
354d0 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69  texNotheld)(sqli
354e0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b  te3_mutex *);.};
354f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35500 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61  : Mutex Verifica
35510 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48  tion Routines {H
35520 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20  17080} <S20130> 
35530 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
35540 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
35550 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69  _held() and sqli
35560 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
35570 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  d() routines.** 
35580 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
35590 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65   use inside asse
355a0 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e  rt() statements.
355b0 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51   {H17081} The SQ
355c0 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
355d0 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
355e0 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
355f0 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
35600 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
35610 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
35620 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
35630 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
35640 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63    {H17082} The c
35650 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
35660 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
35670 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
35680 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
35690 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
356a0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
356b0 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37  EBUG flag.  {A17
356c0 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75  087} External mu
356d0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
356e0 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20  ons.** are only 
356f0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
35700 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ide these routin
35710 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42  es if SQLITE_DEB
35720 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64  UG is.** defined
35730 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69   and if NDEBUG i
35740 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a  s not defined..*
35750 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68  *.** {H17083} Th
35760 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
35770 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
35780 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
35790 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
357a0 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
357b0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
357c0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
357d0 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
357e0 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69  * {X17084} The i
357f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35800 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
35810 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
35820 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
35830 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
35840 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74  ually work. If t
35850 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35860 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  n does not provi
35870 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65  de working.** ve
35880 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20  rsions of these 
35890 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f  routines, it sho
358a0 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f  uld at least pro
358b0 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20  vide stubs that 
358c0 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e  always.** return
358d0 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e   true so that on
358e0 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73  e does not get s
358f0 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f  purious assertio
35900 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a  n failures..**.*
35910 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68  * {H17085} If th
35920 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
35930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
35940 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
35950 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
35960 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
35970 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d  return 1.  {END}
35980 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
35990 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
359a0 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
359b0 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
359c0 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
359d0 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
359e0 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
359f0 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
35a00 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
35a10 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
35a20 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
35a30 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
35a40 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
35a50 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
35a60 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
35a70 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
35a80 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
35a90 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
35aa0 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
35ab0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
35ac0 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48  thing to do.  {H
35ad0 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74  17086} The sqlit
35ae0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
35af0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
35b00 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
35b10 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
35b20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
35b40 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
35b50 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
35b60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
35b70 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
35b80 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
35b90 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70  I3REF: Mutex Typ
35ba0 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37  es {H17001} <H17
35bb0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  000>.**.** The [
35bc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35bd0 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
35be0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
35bf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
35c00 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
35c10 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
35c20 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
35c30 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74  et of static mut
35c40 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20  exes may change 
35c50 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20  from one SQLite 
35c60 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a  release to the.*
35c70 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
35c80 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72  tions that overr
35c90 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  ide the built-in
35ca0 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73   mutex logic mus
35cb0 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  t be.** prepared
35cc0 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20   to accommodate 
35cd0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
35ce0 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64  c mutexes..*/.#d
35cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
35d00 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
35d10 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
35d20 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
35d30 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
35d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
35d50 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
35d60 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
35d70 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
35d80 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
35d90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
35da0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
35db0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
35dc0 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
35dd0 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64  * NOT USED */.#d
35de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
35df0 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20  EX_STATIC_OPEN  
35e00 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
35e10 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a  3BtreeOpen() */.
35e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
35e30 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
35e40 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
35e50 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
35e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
35e70 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
35e80 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
35e90 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65  page list */.#de
35ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
35eb0 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20  X_STATIC_LRU2   
35ec0 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67     7  /* lru pag
35ed0 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  e list */../*.**
35ee0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
35ef0 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f  eve the mutex fo
35f00 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
35f10 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d  nection {H17002}
35f20 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H17000>.**.** 
35f30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
35f40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
35f60 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  tex] object that
35f70 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20   .** serializes 
35f80 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64  access to the [d
35f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35fa0 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65  on] given in the
35fb0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65   argument.** whe
35fc0 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  n the [threading
35fd0 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c   mode] is Serial
35fe0 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ized..** If the 
35ff0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
36000 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   is Single-threa
36010 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61  d or Multi-threa
36020 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72  d then this.** r
36030 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
36040 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36050 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
36060 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  *sqlite3_db_mute
36070 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  x(sqlite3*);../*
36080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
36090 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
360a0 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
360b0 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38  s {H11300} <S308
360c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  00>.**.** {H1130
360d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
360e0 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
360f0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
36100 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f  a direct call to
36110 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e   the.** xFileCon
36120 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20  trol method for 
36130 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
36140 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
36150 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
36160 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
36170 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66  database identif
36180 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
36190 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31  d argument. {H11
361a0 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65  302} The.** name
361b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
361c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73   is the name ass
361d0 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74  igned to the dat
361e0 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20  abase by the.** 
361f0 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74  <a href="lang_at
36200 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43  tach.html">ATTAC
36210 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e  H</a> SQL comman
36220 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68  d that opened th
36230 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b  e.** database. {
36240 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72  H11303} To contr
36250 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  ol the main data
36260 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74  base file, use t
36270 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a  he name "main".*
36280 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * or a NULL poin
36290 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68  ter. {H11304} Th
362a0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
362b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
362c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
362d0 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65   are passed dire
362e0 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20  ctly through to 
362f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
36300 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20  hird parameters 
36310 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43  of.** the xFileC
36320 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20  ontrol method.  
36330 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74  {H11305} The ret
36340 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
36350 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a   xFileControl.**
36360 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20   method becomes 
36370 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36380 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
36390 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d  ..**.** {H11306}
363a0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
363b0 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
363c0 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
363d0 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
363e0 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
363f0 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
36400 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
36410 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d  turned. {H11307}
36420 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63   This error.** c
36430 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d  ode is not remem
36440 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e  bered and will n
36450 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62  ot be recalled b
36460 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
36470 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  de()].** or [sql
36480 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20  ite3_errmsg()]. 
36490 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64  {A11308} The und
364a0 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
364b0 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
364c0 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
364d0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
364e0 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69  {A11309} There i
364f0 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74  s no way to dist
36500 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a  inguish between.
36510 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20  ** an incorrect 
36520 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53  zDbName and an S
36530 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75  QLITE_ERROR retu
36540 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  rn from the unde
36550 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43  rlying.** xFileC
36560 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b  ontrol method. {
36570 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  END}.**.** See a
36580 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  lso: [SQLITE_FCN
36590 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f  TL_LOCKSTATE].*/
365a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  .int sqlite3_fil
365b0 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65  e_control(sqlite
365c0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
365d0 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c  zDbName, int op,
365e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
365f0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e  CAPI3REF: Testin
36600 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31  g Interface {H11
36610 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  400} <S30800>.**
36620 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36630 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69  test_control() i
36640 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
36650 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74   to read out int
36660 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f  ernal.** state o
36670 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20  f SQLite and to 
36680 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e  inject faults in
36690 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65  to SQLite for te
366a0 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65  sting.** purpose
366b0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
366c0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70  rameter is an op
366d0 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61  eration code tha
366e0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
366f0 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e  the number, mean
36700 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69  ing, and operati
36710 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71  on of all subseq
36720 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e  uent parameters.
36730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
36740 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72  rface is not for
36750 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74   use by applicat
36760 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73  ions.  It exists
36770 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76   solely.** for v
36780 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72  erifying the cor
36790 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f  rect operation o
367a0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
367b0 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67  rary.  Depending
367c0 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53  .** on how the S
367d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73  QLite library is
367e0 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20   compiled, this 
367f0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
36800 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a  not exist..**.**
36810 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
36820 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f  the operation co
36830 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69  des, their meani
36840 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74  ngs, the paramet
36850 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65  ers.** they take
36860 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20  , and what they 
36870 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65  do are all subje
36880 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
36890 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20  hout notice..** 
368a0 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74  Unlike most of t
368b0 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74  he SQLite API, t
368c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
368d0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
368e0 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e  o.** operate con
368f0 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f  sistently from o
36900 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
36910 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73  e next..*/.int s
36920 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74  qlite3_test_cont
36930 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  rol(int op, ...)
36940 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36950 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72  F: Testing Inter
36960 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43  face Operation C
36970 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48  odes {H11410} <H
36980 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11400>.**.** The
36990 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
369a0 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61   the valid opera
369b0 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65  tion code parame
369c0 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20  ters used.** as 
369d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
369e0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
369f0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a  est_control()]..
36a00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61  **.** These para
36a10 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72  meters and their
36a20 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75   meanings are su
36a30 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a  bject to change.
36a40 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ** without notic
36a50 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73  e.  These values
36a60 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67   are for testing
36a70 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a   purposes only..
36a80 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
36a90 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61  should not use a
36aa0 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  ny of these para
36ab0 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a  meters or the.**
36ac0 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63   [sqlite3_test_c
36ad0 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
36ae0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
36af0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
36b00 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20  PRNG_SAVE       
36b10 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
36b20 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
36b30 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20  RL_PRNG_RESTORE 
36b40 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
36b50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
36b60 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54  TCTRL_PRNG_RESET
36b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
36b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36b90 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f  TESTCTRL_BITVEC_
36ba0 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20  TEST            
36bb0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
36bc0 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c  TE_TESTCTRL_FAUL
36bd0 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20  T_INSTALL       
36be0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
36bf0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42  QLITE_TESTCTRL_B
36c00 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f  ENIGN_MALLOC_HOO
36c10 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e  KS     10.#defin
36c20 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
36c30 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20  L_PENDING_BYTE  
36c40 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
36c50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
36c60 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20 20  CTRL_ASSERT     
36c70 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
36c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
36c90 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20 20  ESTCTRL_ALWAYS  
36ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36cb0 31 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  13../*.** CAPI3R
36cc0 45 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69  EF: SQLite Runti
36cd0 6d 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30  me Status {H1720
36ce0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45  0} <S60200>.** E
36cf0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
36d00 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
36d10 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72   is used to retr
36d20 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61  ieve runtime sta
36d30 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  tus information.
36d40 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65  ** about the pre
36d50 66 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69  formance of SQLi
36d60 74 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c  te, and optional
36d70 6c 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69  ly to reset vari
36d80 6f 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72  ous.** highwater
36d90 20 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72   marks.  The fir
36da0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
36db0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66  n integer code f
36dc0 6f 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66  or.** the specif
36dd0 69 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ic parameter to 
36de0 6d 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e  measure.  Recogn
36df0 69 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64  ized integer cod
36e00 65 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65  es.** are of the
36e10 20 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54   form [SQLITE_ST
36e20 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44  ATUS_MEMORY_USED
36e30 20 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53   | SQLITE_STATUS
36e40 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75  _...]..** The cu
36e50 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74  rrent value of t
36e60 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
36e70 72 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70  returned into *p
36e80 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  Current..** The 
36e90 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64  highest recorded
36ea0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
36eb0 65 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65  ed in *pHighwate
36ec0 72 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65  r.  If the.** re
36ed0 73 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c  setFlag is true,
36ee0 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73   then the highes
36ef0 74 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69  t record value i
36f00 73 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a  s reset after.**
36f10 20 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20   *pHighwater is 
36f20 77 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61  written. Some pa
36f30 72 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20  rameters do not 
36f40 72 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65  record the highe
36f50 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f  st.** value.  Fo
36f60 72 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65  r those paramete
36f70 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73  rs.** nothing is
36f80 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
36f90 48 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68  Highwater and th
36fa0 65 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69  e resetFlag is i
36fb0 67 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  gnored..** Other
36fc0 20 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f   parameters reco
36fd0 72 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68  rd only the high
36fe0 77 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e  water mark and n
36ff0 6f 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  ot the current.*
37000 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
37010 65 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d  ese latter param
37020 65 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73  eters nothing is
37030 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
37040 43 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  Current..**.** T
37050 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
37060 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  rns SQLITE_OK on
37070 20 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e   success and a n
37080 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f  on-zero.** [erro
37090 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
370a0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  re..**.** This r
370b0 6f 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64  outine is thread
370c0 73 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20  safe but is not 
370d0 61 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f  atomic.  This ro
370e0 75 74 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c  utine can.** cal
370f0 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20  led while other 
37100 74 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e  threads are runn
37110 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20  ing the same or 
37120 64 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65  different SQLite
37130 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20  .** interfaces. 
37140 20 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c   However the val
37150 75 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20  ues returned in 
37160 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a  *pCurrent and.**
37170 20 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66   *pHighwater ref
37180 6c 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20  lect the status 
37190 6f 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66  of SQLite at dif
371a0 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e  ferent points in
371b0 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20   time.** and it 
371c0 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74  is possible that
371d0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
371e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
371f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
37200 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d   between the tim
37210 65 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e  es when *pCurren
37220 74 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65  t and *pHighwate
37230 72 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a  r are written..*
37240 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
37250 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
37260 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  s()].*/.SQLITE_E
37270 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
37280 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69  sqlite3_status(i
37290 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72  nt op, int *pCur
372a0 72 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68  rent, int *pHigh
372b0 77 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74  water, int reset
372c0 46 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  Flag);.../*.** C
372d0 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20  API3REF: Status 
372e0 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32  Parameters {H172
372f0 35 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20  50} <H17200>.** 
37300 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
37310 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
37320 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67   constants desig
37330 6e 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e  nate various run
37340 2d 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 72  -time status par
37350 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20  ameters.** that 
37360 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
37370 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  by [sqlite3_stat
37380 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  us()]..**.** <dl
37390 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
373a0 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53  STATUS_MEMORY_US
373b0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
373c0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
373d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f   the current amo
373e0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68  unt of memory ch
373f0 65 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69  ecked out.** usi
37400 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
37410 6f 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69  oc()], either di
37420 72 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65  rectly or indire
37430 63 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69  ctly.  The.** fi
37440 67 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61  gure includes ca
37450 6c 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c  lls made to [sql
37460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
37470 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
37480 6e 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61  n.** and interna
37490 6c 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62  l memory usage b
374a0 79 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  y the SQLite lib
374b0 72 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d  rary.  Scratch m
374c0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  emory.** control
374d0 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  led by [SQLITE_C
374e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
374f0 6e 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 67  nd auxiliary pag
37500 65 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72  e-cache.** memor
37510 79 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  y controlled by 
37520 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
37530 41 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74  AGECACHE] is not
37540 20 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20   included in.** 
37550 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20  this parameter. 
37560 20 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75   The amount retu
37570 72 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d 20  rned is the sum 
37580 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  of the allocatio
37590 6e 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65  n.** sizes as re
375a0 70 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 53  ported by the xS
375b0 69 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73  ize method in [s
375c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
375d0 64 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ds].</dd>.**.** 
375e0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
375f0 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64  S_MALLOC_SIZE</d
37600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70  t>.** <dd>This p
37610 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73  arameter records
37620 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d   the largest mem
37630 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
37640 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64  equest.** handed
37650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
37660 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
37670 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f  e3_realloc()] (o
37680 72 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72  r their.** inter
37690 6e 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29  nal equivalents)
376a0 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75  .  Only the valu
376b0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68  e returned in th
376c0 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72  e.** *pHighwater
376d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
376e0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
376f0 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e   is of interest.
37700 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20    .** The value 
37710 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
37720 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d   *pCurrent param
37730 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65  eter is undefine
37740 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
37750 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
37760 50 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f  PAGECACHE_USED</
37770 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
37780 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e  parameter return
37790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
377a0 70 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f  pages used out o
377b0 66 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61  f the.** [pageca
377c0 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
377d0 61 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63  ator] that was c
377e0 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20  onfigured using 
377f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
37800 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20  IG_PAGECACHE].  
37810 54 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74  The.** value ret
37820 75 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65  urned is in page
37830 73 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e  s, not in bytes.
37840 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
37850 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
37860 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57  GECACHE_OVERFLOW
37870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
37880 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75  s parameter retu
37890 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
378a0 66 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 20  f bytes of page 
378b0 63 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  cache.** allocat
378c0 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20  ion which could 
378d0 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65  not be statisfie
378e0 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
378f0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
37900 45 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64  E].** buffer and
37910 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f   where forced to
37920 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71   overflow to [sq
37930 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
37940 20 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65    The.** returne
37950 64 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73  d value includes
37960 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61   allocations tha
37970 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63  t overflowed bec
37980 61 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65  ause they.** whe
37990 72 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68  re too large (th
379a0 65 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74  ey were larger t
379b0 68 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72  han the "sz" par
379c0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
379d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
379e0 43 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f  CACHE]) and allo
379f0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65  cations that ove
37a00 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a  rflowed because.
37a10 2a 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20  ** no space was 
37a20 6c 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65  left in the page
37a30 20 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a   cache.</dd>.**.
37a40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54  ** <dt>SQLITE_ST
37a50 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53  ATUS_PAGECACHE_S
37a60 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IZE</dt>.** <dd>
37a70 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72  This parameter r
37a80 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65  ecords the large
37a90 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  st memory alloca
37aa0 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20  tion request.** 
37ab0 68 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63  handed to [pagec
37ac0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
37ad0 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68  cator].  Only th
37ae0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
37af0 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67   in the.** *pHig
37b00 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72  hwater parameter
37b10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61   to [sqlite3_sta
37b20 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74  tus()] is of int
37b30 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20  erest.  .** The 
37b40 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e  value written in
37b50 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74  to the *pCurrent
37b60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e   parameter is un
37b70 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
37b80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
37b90 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53  TATUS_SCRATCH_US
37ba0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
37bb0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65  his parameter re
37bc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
37bd0 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20   of allocations 
37be0 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a  used out of the.
37bf0 2a 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f  ** [scratch memo
37c00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
37c10 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a  nfigured using.*
37c20 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
37c30 5f 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20  _SCRATCH].  The 
37c40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
37c50 73 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  s in allocations
37c60 2c 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65  , not.** in byte
37c70 73 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67  s.  Since a sing
37c80 6c 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e  le thread may on
37c90 6c 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61  ly have one scra
37ca0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tch allocation.*
37cb0 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74  * outstanding at
37cc0 20 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61   time, this para
37cd0 6d 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72  meter also repor
37ce0 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
37cf0 20 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e   threads.** usin
37d00 67 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  g scratch memory
37d10 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
37d20 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
37d30 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  t>SQLITE_STATUS_
37d40 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57  SCRATCH_OVERFLOW
37d50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
37d60 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75  s parameter retu
37d70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
37d80 66 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74  f bytes of scrat
37d90 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ch memory.** all
37da0 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f  ocation which co
37db0 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69  uld not be stati
37dc0 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51  sfied by the [SQ
37dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
37de0 54 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61  TCH].** buffer a
37df0 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20  nd where forced 
37e00 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b  to overflow to [
37e10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37e20 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a  ].  The values.*
37e30 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75  * returned inclu
37e40 64 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63  de overflows bec
37e50 61 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74  ause the request
37e60 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61  ed allocation wa
37e70 73 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20  s too.** larger 
37e80 28 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 73  (that is, becaus
37e90 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  e the requested 
37ea0 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c  allocation was l
37eb0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a  arger than the.*
37ec0 2a 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72  * "sz" parameter
37ed0 20 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   to [SQLITE_CONF
37ee0 49 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64  IG_SCRATCH]) and
37ef0 20 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61   because no scra
37f00 74 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c  tch buffer.** sl
37f10 6f 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 62  ots were availab
37f20 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  le..** </dd>.**.
37f30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54  ** <dt>SQLITE_ST
37f40 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a  ATUS_SCRATCH_SIZ
37f50 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
37f60 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63  is parameter rec
37f70 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74  ords the largest
37f80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37f90 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61  on request.** ha
37fa0 6e 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68  nded to [scratch
37fb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
37fc0 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61  r].  Only the va
37fd0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
37fe0 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  the.** *pHighwat
37ff0 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  er parameter to 
38000 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
38010 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73  )] is of interes
38020 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75  t.  .** The valu
38030 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  e written into t
38040 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72  he *pCurrent par
38050 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69  ameter is undefi
38060 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
38070 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
38080 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f  S_PARSER_STACK</
38090 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
380a0 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64  parameter record
380b0 73 20 74 68 65 20 64 65 65 70 65 73 74 20 70 61  s the deepest pa
380c0 72 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20  rser stack.  It 
380d0 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69  is only.** meani
380e0 6e 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20  ngful if SQLite 
380f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
38100 20 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43   [YYTRACKMAXSTAC
38110 4b 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a  KDEPTH].</dd>.**
38120 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77   </dl>.**.** New
38130 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65   status paramete
38140 72 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  rs may be added 
38150 66 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d  from time to tim
38160 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
38170 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f  LITE_STATUS_MEMO
38180 52 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20  RY_USED         
38190 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
381a0 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43  E_STATUS_PAGECAC
381b0 48 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a  HE_USED       1.
381c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
381d0 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f  TATUS_PAGECACHE_
381e0 4f 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65  OVERFLOW   2.#de
381f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
38200 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20  US_SCRATCH_USED 
38210 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
38220 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
38230 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57  SCRATCH_OVERFLOW
38240 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
38250 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c  QLITE_STATUS_MAL
38260 4c 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20  LOC_SIZE        
38270 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
38280 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52  TE_STATUS_PARSER
38290 5f 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 36  _STACK         6
382a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
382b0 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45  STATUS_PAGECACHE
382c0 5f 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64  _SIZE       7.#d
382d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
382e0 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45  TUS_SCRATCH_SIZE
382f0 20 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a           8../*.*
38300 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
38310 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
38320 53 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20  Status {H17500} 
38330 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S60200>.** EXPE
38340 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
38350 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
38360 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
38370 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73  e runtime status
38380 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a   information .**
38390 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
383a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
383b0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
383c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
383d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
383e0 6e 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20  nnection object 
383f0 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74  to be interrogat
38400 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
38410 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74  argument.** is t
38420 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
38430 69 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75  interrogate.  Cu
38440 72 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c  rrently, the onl
38450 79 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a  y allowed value.
38460 2a 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  ** for the secon
38470 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b  d parameter is [
38480 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f  SQLITE_DBSTATUS_
38490 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e  LOOKASIDE_USED].
384a0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f  .** Additional o
384b0 70 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65  ptions will like
384c0 6c 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 74  ly appear in fut
384d0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
384e0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
384f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
38500 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
38510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 72   parameter is wr
38520 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72  itten into *pCur
38530 0a 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68  .** and the high
38540 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75  est instantaneou
38550 73 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 74  s value is writt
38560 65 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e  en into *pHiwtr.
38570 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65    If.** the rese
38580 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68  tFlg is true, th
38590 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 69  en the highest i
385a0 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c  nstantaneous val
385b0 75 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62  ue is.** reset b
385c0 61 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ack down to the 
385d0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a  current value..*
385e0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
385f0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
38600 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
38610 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a  tmt_status()]..*
38620 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
38630 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
38640 33 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69  3_db_status(sqli
38650 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e  te3*, int op, in
38660 74 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48  t *pCur, int *pH
38670 69 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46  iwtr, int resetF
38680 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lg);../*.** CAPI
38690 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72  3REF: Status Par
386a0 61 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61  ameters for data
386b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
386c0 20 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30   {H17520} <H1750
386d0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
386e0 41 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20  AL.**.** Status 
386f0 76 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74  verbs for [sqlit
38700 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e  e3_db_status()].
38710 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
38720 64 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54  dt>SQLITE_DBSTAT
38730 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45  US_LOOKASIDE_USE
38740 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
38750 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74  is parameter ret
38760 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
38770 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
38780 6f 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e  ory slots curren
38790 74 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f  tly.** checked o
387a0 75 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ut.</dd>.** </dl
387b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
387c0 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f  ITE_DBSTATUS_LOO
387d0 4b 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20  KASIDE_USED     
387e0 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  0.../*.** CAPI3R
387f0 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
38800 74 65 6d 65 6e 74 20 53 7