/ Hex Artifact Content
Login

Artifact 9fe53ec7a8310d7d18d482b85e46f5556abfd1de:


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 37 20 32 30 30 39 2f 30  n,v 1.457 2009/0
05f0: 36 2f 30 39 20 31 39 3a 35 33 3a 35 38 20 64 72  6/09 19:53:58 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 61 6e 20 38 2d   A pointer an 8-
b7c0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
b7d0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
b7e0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
b7f0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
b800: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
b810: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
b820: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
b830: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
b840: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
b850: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
b860: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
b870: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
b880: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
b890: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
b8a0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
b8b0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
b8c0: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
b8d0: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
b8e0: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
b8f0: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69  equired due to i
b900: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
b910: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
b920: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b930: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
b940: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
b950: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
b960: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
b970: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
b980: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
b990: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
b9a0: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e  tch buffer at on
b9b0: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73  ce per thread, s
b9c0: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
b9d0: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65   set to the expe
b9e0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
b9f0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20  ber of threads. 
ba00: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d   The sz.** param
ba10: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36  eter should be 6
ba20: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20   times the size 
ba30: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
ba40: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
ba50: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75  e..** Scratch bu
ba60: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61  ffers are used a
ba70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74  s part of the bt
ba80: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72  ree balance oper
ba90: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68  ation.  If.** Th
baa0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72  e btree balancer
bab0: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
bac0: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  l memory beyond 
bad0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
bae0: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62   by.** scratch b
baf0: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20  uffers or if no 
bb00: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73  scratch buffer s
bb10: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65  pace is specifie
bb20: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  d, then SQLite.*
bb30: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  * goes to [sqlit
bb40: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20  e3_malloc()] to 
bb50: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
bb60: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e  y it needs.</dd>
bb70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bb80: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
bb90: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
bba0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bbb0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bbc0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bbd0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
bbe0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
bbf0: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
bc00: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
bc10: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
bc20: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
bc30: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
bc40: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
bc50: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
bc60: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
bc70: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
bc80: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
bc90: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
bca0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
bcb0: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
bcc0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
bcd0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bce0: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
bcf0: 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
bd00: 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
bd10: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
bd20: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
bd30: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
bd40: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
bd50: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
bd60: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
bd70: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
bd80: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
bd90: 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
bda0: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
bdb0: 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
bdc0: 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
bdd0: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
bde0: 65 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70  e header.  The p
bdf0: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
be00: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
be10: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
be20: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
be30: 74 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20  tecture.  It is 
be40: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
be50: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
be60: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
be70: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
be80: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
be90: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
bea0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
beb0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
bec0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
bed0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
bee0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
bef0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
bf00: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
bf10: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
bf20: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
bf30: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
bf40: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
bf50: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
bf60: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
bf70: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
bf80: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
bf90: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
bfa0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
bfb0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
bfc0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
bfd0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
bfe0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
bff0: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
c000: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
c010: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c020: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
c030: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
c040: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
c050: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
c060: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
c070: 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20  on. The pointer 
c080: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
c090: 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
c0a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
c0b0: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
c0c0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
c0d0: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
c0e0: 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
c0f0: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
c100: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c110: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
c120: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c130: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c140: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c150: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c160: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
c170: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
c180: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c190: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
c1a0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
c1b0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
c1c0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
c1d0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
c1e0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
c1f0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
c200: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
c210: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
c220: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c230: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
c240: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
c250: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
c260: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
c270: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
c280: 7a 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ze..** If the fi
c290: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
c2a0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
c2b0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
c2c0: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
c2d0: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
c2e0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
c2f0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
c300: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
c310: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
c320: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
c330: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
c340: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c350: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
c360: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
c370: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
c380: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
c390: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
c3a0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
c3b0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
c3c0: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
c3d0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
c3e0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
c3f0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
c400: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
c410: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
c420: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
c430: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
c440: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
c450: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
c460: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
c470: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
c480: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
c490: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
c4a0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
c4b0: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
c4c0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c4d0: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
c4e0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c4f0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c500: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c510: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c520: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c530: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c540: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
c550: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
c560: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
c570: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
c580: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
c590: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
c5a0: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
c5b0: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
c5c0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
c5d0: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  SQLite.</dd>.**.
c5e0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c5f0: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
c600: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c610: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
c620: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
c630: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
c640: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
c650: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
c660: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
c670: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
c680: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
c690: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
c6a0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
c6b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
c6c0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
c6d0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  utex routines..*
c6e0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
c6f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
c700: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
c710: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
c720: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
c730: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
c740: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
c750: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
c760: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
c770: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
c780: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
c790: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c7a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
c7b0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
c7c0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c7d0: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
c7e0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
c7f0: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
c800: 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20  emory allcation 
c810: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
c820: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
c830: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
c840: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c850: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
c860: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
c870: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
c880: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
c890: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
c8a0: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
c8b0: 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  nection.</dd>.**
c8c0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c8d0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74  ONFIG_PCACHE</dt
c8e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c8f0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
c900: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
c910: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
c920: 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
c930: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
c940: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
c950: 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
c960: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
c970: 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
c980: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
c990: 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65  ntation.  SQLite
c9a0: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
c9b0: 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
c9c0: 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
c9d0: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
c9e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
c9f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ca00: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
ca10: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
ca20: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
ca30: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
ca40: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ca50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
ca60: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
ca70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ca80: 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
ca90: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
caa0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
cab0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
cac0: 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f  o that object.</
cad0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
cae0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
caf0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
cb00: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
cb10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cb20: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
cb30: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
cb40: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
cb50: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
cb60: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
cb70: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
cb80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
cb90: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
cba0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
cbb0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
cbc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
cbd0: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
cbe0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
cbf0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
cc00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cc10: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
cc20: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
cc30: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
cc40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cc50: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
cc60: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
cc70: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
cc80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cc90: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
cca0: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
ccb0: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
ccc0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
ccd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
cce0: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
ccf0: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
cd00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cd10: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
cd20: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
cd30: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
cd40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cd50: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
cd60: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
cd70: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
cd80: 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
cd90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
cda0: 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
cdb0: 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
cdc0: 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
cdd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
cde0: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
cdf0: 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
ce00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ce10: 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
ce20: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
ce30: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
ce40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ce50: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
ce60: 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
ce70: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
ce80: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
ce90: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
cea0: 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31  on Options {H101
ceb0: 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  70} <S20000>.** 
cec0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
ced0: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
cee0: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
cef0: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
cf00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cf10: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
cf20: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
cf30: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
cf40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
cf50: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
cf60: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
cf70: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
cf80: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
cf90: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
cfa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
cfb0: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
cfc0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
cfd0: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
cfe0: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
cff0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
d000: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
d010: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
d020: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
d030: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
d040: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
d050: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
d060: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
d070: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
d080: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
d090: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
d0a0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
d0b0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
d0c0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
d0d0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
d0e0: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
d0f0: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
d100: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
d110: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
d120: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d130: 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
d140: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
d150: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
d160: 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
d170: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
d180: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
d190: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
d1a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d1b0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
d1c0: 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
d1d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
d1e0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
d1f0: 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
d200: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
d210: 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
d220: 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
d230: 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
d240: 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65 20 66 69 72  mory..** The fir
d250: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  st argument may 
d260: 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
d270: 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
d280: 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
d290: 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
d2a0: 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
d2b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
d2c0: 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  )].  The second 
d2d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
d2e0: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
d2f0: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
d300: 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68   slot and the th
d310: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
d320: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
d330: 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
d340: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
d350: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
d360: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
d370: 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
d380: 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
d390: 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
d3a0: 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
d3b0: 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a  guments.</dd>.**
d3c0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
d3d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
d3e0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
d3f0: 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
d400: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a   int int */.../*
d410: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
d420: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
d430: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
d440: 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c  Codes {H12200} <
d450: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
d460: 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
d470: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
d480: 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
d490: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
d4a0: 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
d4b0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
d4c0: 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
d4d0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
d4e0: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
d4f0: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
d500: 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
d510: 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
d520: 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73  y considerations
d530: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
d540: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31  ents:.** [H12201
d550: 5d 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e  ] [H12202].*/.in
d560: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
d570: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
d580: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
d590: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
d5a0: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
d5b0: 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30  rt Rowid {H12220
d5c0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
d5d0: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61   Each entry in a
d5e0: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
d5f0: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
d600: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
d610: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
d620: 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
d630: 77 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64  wid"]. The rowid
d640: 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
d650: 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
d660: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
d670: 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
d680: 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
d690: 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
d6a0: 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
d6b0: 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
d6c0: 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
d6d0: 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74  columns. If.** t
d6e0: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
d6f0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
d700: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
d710: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
d720: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
d730: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
d740: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   rowid..**.** Th
d750: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
d760: 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
d770: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
d780: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
d790: 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
d7a0: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
d7b0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
d7c0: 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
d7d0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d7e0: 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65  nt.  If no succe
d7f0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
d800: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
d810: 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
d820: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d830: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
d840: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ned..**.** If an
d850: 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
d860: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
d870: 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
d880: 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
d890: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
d8a0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
d8b0: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
d8c0: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
d8d0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
d8e0: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
d8f0: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
d900: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
d910: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
d920: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
d930: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
d940: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
d950: 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
d960: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52  .**.** An [INSER
d970: 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
d980: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
d990: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
d9a0: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
d9b0: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
d9c0: 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
d9d0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
d9e0: 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
d9f0: 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53  utine.  Thus INS
da00: 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
da10: 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
da20: 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
da30: 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
da40: 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
da50: 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
da60: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
da70: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
da80: 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
da90: 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68  rtion fails.  Wh
daa0: 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
dab0: 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
dac0: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
dad0: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
dae0: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
daf0: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
db00: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
db10: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
db20: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
db30: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
db40: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
db50: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
db60: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
db70: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
db80: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
db90: 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
dba0: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
dbb0: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
dbc0: 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
dbd0: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
dbe0: 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
dbf0: 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
dc00: 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
dc10: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
dc20: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
dc30: 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 32 32  * [H12221] [H122
dc40: 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  23].**.** If a s
dc50: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
dc60: 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
dc70: 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
dc80: 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
dc90: 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
dca0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
dcb0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
dcc0: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
dcd0: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
dce0: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
dcf0: 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
dd00: 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
dd10: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
dd20: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
dd30: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
dd40: 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
dd50: 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
dd60: 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
dd70: 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
dd80: 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
dd90: 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
dda0: 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
ddb0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
ddc0: 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
ddd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dde0: 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
ddf0: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
de00: 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36  d {H12240} <S106
de10: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
de20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
de30: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
de40: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
de50: 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
de60: 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
de70: 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
de80: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
de90: 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
dea0: 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
deb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
dec0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
ded0: 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
dee0: 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63  meter..** Only c
def0: 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
df00: 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
df10: 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
df20: 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
df30: 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
df40: 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
df50: 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
df60: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
df70: 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65  .** triggers are
df80: 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73   not counted. Us
df90: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
dfa0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
dfb0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
dfc0: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
dfd0: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
dfe0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
dff0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
e000: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e  gers..**.** Chan
e010: 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
e020: 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
e030: 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
e040: 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
e050: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
e060: 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
e070: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
e080: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72  nted..**.** A "r
e090: 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
e0a0: 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
e0b0: 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
e0c0: 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
e0d0: 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
e0e0: 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
e0f0: 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
e100: 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
e110: 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
e120: 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
e130: 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
e140: 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
e150: 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
e160: 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
e170: 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
e180: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
e190: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
e1a0: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
e1b0: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
e1c0: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
e1d0: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
e1e0: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
e1f0: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
e200: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
e210: 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
e220: 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
e230: 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
e240: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
e250: 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
e260: 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
e270: 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
e280: 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
e290: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
e2a0: 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
e2b0: 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
e2c0: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
e2d0: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
e2e0: 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
e2f0: 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
e300: 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
e310: 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
e320: 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
e330: 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
e340: 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
e350: 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** Calling [sqli
e360: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
e370: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
e380: 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
e390: 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
e3a0: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
e3b0: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  text..**.** This
e3c0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
e3d0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
e3e0: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
e3f0: 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
e400: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
e410: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
e420: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
e430: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
e440: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
e450: 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65  .**.** Thus, whe
e460: 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
e470: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
e480: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
e490: 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
e4a0: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
e4b0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
e4c0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e4d0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
e4e0: 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
e4f0: 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
e500: 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64    Within the bod
e510: 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
e520: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
e530: 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
e540: 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
e550: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
e560: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
e570: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
e580: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
e590: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
e5a0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
e5b0: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
e5c0: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
e5d0: 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
e5e0: 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
e5f0: 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
e600: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
e610: 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
e620: 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
e630: 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
e640: 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
e650: 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
e660: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
e670: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
e680: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68  interface and th
e690: 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
e6a0: 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a  ges pragma]..**.
e6b0: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
e6c0: 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 31  .** [H12241] [H1
e6d0: 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61  2243].**.** If a
e6e0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
e6f0: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
e700: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
e710: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
e720: 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
e730: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
e740: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
e750: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
e760: 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
e770: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
e780: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
e790: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
e7a0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
e7b0: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
e7c0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
e7d0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d  odified {H12260}
e7e0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
e7f0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
e800: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
e810: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
e820: 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
e830: 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
e840: 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
e850: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
e860: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e870: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
e880: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
e890: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
e8a0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 0a 2a  nges from all .*
e8b0: 2a 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  * [CREATE TRIGGE
e8c0: 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
e8d0: 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c  texts.  However,
e8e0: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
e8f0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
e900: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
e910: 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
e920: 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
e930: 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
e940: 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
e950: 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
e960: 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
e970: 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
e980: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
e990: 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
e9a0: 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
e9b0: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
e9c0: 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
e9d0: 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
e9e0: 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
e9f0: 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
ea00: 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
ea10: 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
ea20: 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65   The changes are
ea30: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
ea40: 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
ea50: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
ea60: 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  m is.** complete
ea70: 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
ea80: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20  ement handle is 
ea90: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
eaa0: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
eab0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
eac0: 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
ead0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
eae0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
eaf0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68  interface and th
eb00: 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
eb10: 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a  ges pragma]..**.
eb20: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
eb30: 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20 5b 48 31  .** [H12261] [H1
eb40: 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61  2263].**.** If a
eb50: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
eb60: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
eb70: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
eb80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
eb90: 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
eba0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
ebb0: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
ebc0: 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
ebd0: 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
ebe0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
ebf0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
ec00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
ec10: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
ec20: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ec30: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
ec40: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
ec50: 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53  uery {H12270} <S
ec60: 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30500>.**.** Thi
ec70: 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
ec80: 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
ec90: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
eca0: 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
ecb0: 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
ecc0: 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
ecd0: 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
ece0: 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
ecf0: 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
ed00: 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
ed10: 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
ed20: 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
ed30: 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
ed40: 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
ed50: 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
ed60: 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
ed70: 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
ed80: 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
ed90: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
eda0: 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
edb0: 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
edc0: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
edd0: 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
ede0: 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
edf0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
ee00: 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
ee10: 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
ee20: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
ee30: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
ee40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
ee50: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
ee60: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
ee70: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
ee80: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
ee90: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
eea0: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
eeb0: 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
eec0: 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
eed0: 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
eee0: 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
eef0: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
ef00: 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
ef10: 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
ef20: 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
ef30: 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
ef40: 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
ef50: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c  on..**.** An SQL
ef60: 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
ef70: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
ef80: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
ef90: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
efa0: 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75  * If the interru
efb0: 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
efc0: 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
efd0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
efe0: 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
eff0: 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
f000: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
f010: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
f020: 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
f030: 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
f040: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
f050: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f060: 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
f070: 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
f080: 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
f090: 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
f0a0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
f0b0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f0c0: 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
f0d0: 74 65 2e 20 20 41 6e 79 20 6e 65 77 20 53 51 4c  te.  Any new SQL
f0e0: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
f0f0: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
f100: 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
f110: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
f120: 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
f130: 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
f140: 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
f150: 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
f160: 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
f170: 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
f180: 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
f190: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
f1a0: 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77  upt() call.  New
f1b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
f1c0: 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
f1d0: 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
f1e0: 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
f1f0: 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
f200: 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
f210: 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
f220: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
f230: 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  )..** A call to 
f240: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f250: 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
f260: 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
f270: 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
f280: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
f290: 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
f2a0: 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
f2b0: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
f2c0: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
f2d0: 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
f2e0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
f2f0: 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
f300: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
f310: 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48 31 32  ** [H12271] [H12
f320: 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  272].**.** If th
f330: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f340: 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
f350: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
f360: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
f370: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
f380: 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
f390: 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
f3a0: 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
f3b0: 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
f3c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f3d0: 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
f3e0: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
f3f0: 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35  s Complete {H105
f400: 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a  10} <S70200>.**.
f410: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f420: 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
f430: 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
f440: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
f450: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
f460: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
f470: 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
f480: 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
f490: 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
f4a0: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
f4b0: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
f4c0: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
f4d0: 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
f4e0: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
f4f0: 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
f500: 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
f510: 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
f520: 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
f530: 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
f540: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73   statement.  A s
f550: 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
f560: 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
f570: 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
f580: 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
f590: 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
f5a0: 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
f5b0: 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
f5c0: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
f5d0: 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
f5e0: 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
f5f0: 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
f600: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
f610: 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
f620: 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
f630: 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
f640: 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
f650: 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
f660: 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
f670: 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
f680: 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
f690: 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
f6a0: 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
f6b0: 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
f6c0: 2e 20 20 57 68 69 74 65 73 70 61 63 65 0a 2a 2a  .  Whitespace.**
f6d0: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
f6e0: 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
f6f0: 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
f700: 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
f710: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
f720: 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
f730: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
f740: 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 61 0a 2a  omplete.  If a.*
f750: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f760: 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
f770: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
f780: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
f790: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
f7a0: 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
f7b0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
f7c0: 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
f7d0: 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
f7e0: 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
f7f0: 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c  QL..**.** If SQL
f800: 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
f810: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
f820: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
f830: 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
f840: 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
f850: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f860: 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
f870: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f880: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
f890: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
f8a0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
f8b0: 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
f8c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
f8d0: 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
f8e0: 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
f8f0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f900: 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
f910: 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
f920: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
f930: 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
f940: 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
f950: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
f960: 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b  ents: [H10511] [
f970: 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68  H10512].**.** Th
f980: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
f990: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
f9a0: 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
f9b0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
f9c0: 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
f9d0: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
f9e0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
f9f0: 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
fa00: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
fa10: 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
fa20: 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
fa30: 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
fa40: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
fa50: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
fa60: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
fa70: 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
fa80: 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
fa90: 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
faa0: 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
fab0: 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
fac0: 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
fad0: 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
fae0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
faf0: 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
fb00: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
fb10: 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
fb20: 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
fb30: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
fb40: 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
fb50: 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
fb60: 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
fb70: 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
fb80: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
fb90: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
fba0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
fbb0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
fbc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
fbd0: 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
fbe0: 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
fbf0: 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
fc00: 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
fc10: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
fc20: 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
fc30: 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
fc40: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
fc50: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
fc60: 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
fc70: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fc80: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
fc90: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
fca0: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
fcb0: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
fcc0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
fcd0: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
fce0: 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
fcf0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
fd00: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
fd10: 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
fd20: 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
fd30: 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
fd40: 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
fd50: 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
fd60: 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
fd70: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
fd80: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
fd90: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
fda0: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
fdb0: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
fdc0: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
fdd0: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
fde0: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
fdf0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
fe00: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
fe10: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
fe20: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
fe30: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
fe40: 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
fe50: 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
fe60: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
fe70: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
fe80: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
fe90: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
fea0: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
feb0: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
fec0: 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
fed0: 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
fee0: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
fef0: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
ff00: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
ff10: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
ff20: 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
ff30: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
ff40: 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
ff50: 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
ff60: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
ff70: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
ff80: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
ff90: 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
ffa0: 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
ffb0: 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
ffc0: 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
ffd0: 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
ffe0: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
fff0: 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
10000 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
10010 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
10020 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
10030 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
10040 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
10050 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
10060 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
10070 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
10080 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
10090 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
100a0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
100b0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
100c0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
100d0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
100e0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
100f0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
10100 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
10110 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
10120 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
10130 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
10140 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
10150 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
10160 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
10170 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
10180 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
10190 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
101a0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
101b0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
101c0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
101d0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
101e0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
101f0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
10200 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
10210 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
10220 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
10230 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
10240 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
10250 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
10260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
10270 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
10280 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
10290 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
102a0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
102b0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
102c0 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
102d0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
102e0 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
102f0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
10300 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
10310 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
10320 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
10330 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
10340 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
10350 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
10360 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
10370 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
10380 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
10390 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
103a0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
103b0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
103c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
103d0 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
103e0 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
103f0 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
10400 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
10410 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
10420 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
10430 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
10440 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
10450 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
10460 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
10470 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
10480 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
10490 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
104a0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
104b0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
104c0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
104d0 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
104e0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
104f0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
10500 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
10510 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
10520 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
10530 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
10540 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
10550 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
10560 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
10570 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
10580 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
10590 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
105a0 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
105b0 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
105c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
105d0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
105e0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
105f0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
10600 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
10610 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
10620 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
10630 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
10640 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
10650 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
10660 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
10670 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
10680 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
10690 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
106a0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
106b0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
106c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
106d0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
106e0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
106f0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
10700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10710 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
10720 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10730 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
10740 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
10750 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
10760 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75  ior..** .** Requ
10770 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
10780 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b  2311] [H12312] [
10790 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31 36 5d  H12314] [H12316]
107a0 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20   [H12318].**.** 
107b0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
107c0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
107d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
107e0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
107f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
10800 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
10810 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
10820 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
10830 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
10840 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
10850 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
10860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10870 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
10880 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53  eout {H12340} <S
10890 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40410>.**.** Thi
108a0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
108b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
108c0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
108d0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
108e0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
108f0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
10900 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
10910 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68  e is locked.  Th
10920 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
10930 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
10940 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
10950 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
10960 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
10970 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
10980 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33  mulated. {H12343
10990 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c  } After "ms" mil
109a0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
109b0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
109c0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
109d0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
109e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
109f0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
10a00 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
10a10 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
10a20 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  D]..**.** Callin
10a30 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
10a40 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
10a50 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
10a60 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
10a70 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
10a80 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
10a90 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
10aa0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
10ab0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
10ac0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
10ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10ae0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
10af0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
10b00 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
10b10 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
10b20 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
10b30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
10b40 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
10b50 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
10b60 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
10b70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
10b80 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  cleared..**.** R
10b90 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
10ba0 5b 48 31 32 33 34 31 5d 20 5b 48 31 32 33 34 33  [H12341] [H12343
10bb0 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e  ] [H12344].*/.in
10bc0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
10bd0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
10be0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
10bf0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
10c00 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
10c10 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
10c20 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31  ies {H12370} <S1
10c30 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  0000>.**.** Defi
10c40 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
10c50 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
10c60 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
10c70 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
10c80 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
10c90 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
10ca0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
10cb0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
10cc0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
10cd0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
10ce0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
10cf0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
10d00 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
10d10 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
10d20 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
10d30 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
10d40 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
10d50 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
10d60 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10d70 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
10d80 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
10d90 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
10da0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
10db0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
10dc0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
10dd0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
10de0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
10df0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
10e00 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
10e10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
10e20 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
10e30 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
10e40 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
10e50 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
10e60 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
10e70 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
10e80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10e90 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
10ea0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
10eb0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
10ec0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
10ed0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
10ee0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
10ef0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
10f00 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
10f10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
10f20 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
10f30 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
10f40 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
10f50 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
10f60 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
10f70 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
10f80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
10f90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
10fa0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
10fb0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
10fc0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
10fd0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
10fe0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
10ff0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
11000 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
11010 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
11020 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11030 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
11040 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
11050 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11060 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
11070 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
11080 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
11090 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
110a0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
110b0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
110c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
110d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
110e0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
110f0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
11100 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
11110 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
11120 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
11130 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
11140 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
11150 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
11160 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
11170 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11180 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
11190 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
111a0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
111b0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
111c0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
111d0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
111e0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
111f0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
11200 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
11210 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
11220 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
11230 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
11240 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
11250 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11260 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
11270 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
11280 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11290 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
112a0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
112b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
112c0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
112d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
112e0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
112f0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11300 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
11310 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11320 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
11330 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11340 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
11350 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
11360 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
11370 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
11380 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
11390 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
113a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
113b0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
113c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
113d0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
113e0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
113f0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
11400 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
11410 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
11420 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
11430 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
11440 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
11450 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
11460 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
11470 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
11480 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
11490 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
114a0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
114b0 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
114c0 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f  d.** pass the po
114d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
114e0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
114f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11500 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
11510 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
11520 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
11530 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
11540 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
11550 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
11560 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
11570 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
11580 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
11590 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
115a0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
115b0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
115c0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
115d0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
115e0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
115f0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
11600 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
11610 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
11620 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
11630 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
11640 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
11650 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
11660 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
11670 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
11680 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
11690 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
116a0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
116b0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
116c0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
116d0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
116e0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
116f0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
11700 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
11710 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
11720 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
11730 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
11740 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
11750 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
11760 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
11770 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
11780 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
11790 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
117a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
117b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
117c0 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ode()] or [sqlit
117d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
117e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
117f0 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48  :.** [H12371] [H
11800 31 32 33 37 33 5d 20 5b 48 31 32 33 37 34 5d 20  12373] [H12374] 
11810 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 33 37 39  [H12376] [H12379
11820 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e  ] [H12382].*/.in
11830 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
11840 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
11850 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
11860 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
11870 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
11880 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
11890 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
118a0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
118b0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
118c0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
118d0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
118e0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
118f0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
11900 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
11910 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
11920 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
11930 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
11940 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
11950 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
11960 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
11970 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
11980 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
11990 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
119a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
119b0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
119c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
119d0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
119e0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
119f0 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
11a00 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
11a10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
11a20 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
11a30 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
11a40 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
11a50 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
11a60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
11a70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
11a80 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
11a90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
11aa0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
11ab0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
11ac0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
11ad0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
11ae0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
11af0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
11b00 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
11b10 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
11b20 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
11b30 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
11b40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
11b50 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
11b60 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
11b70 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
11b80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
11b90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
11ba0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
11bb0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
11bc0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
11bd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
11be0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
11bf0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
11c00 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
11c10 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
11c20 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
11c30 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
11c40 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
11c50 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
11c60 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
11c70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
11c80 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
11c90 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
11ca0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
11cb0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
11cc0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
11cd0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
11ce0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
11cf0 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
11d00 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
11d10 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
11d20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
11d30 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
11d40 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
11d50 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
11d60 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
11d70 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
11d80 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
11d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
11da0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
11db0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
11dc0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
11dd0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
11de0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
11df0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
11e00 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11e10 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
11e20 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
11e30 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
11e40 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
11e50 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
11e60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
11e70 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
11e80 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
11e90 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
11ea0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
11eb0 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
11ec0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
11ed0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
11ee0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
11ef0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
11f00 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11f10 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
11f20 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
11f30 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
11f40 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
11f50 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
11f60 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
11f70 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
11f80 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
11f90 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
11fa0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
11fb0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
11fc0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
11fd0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
11fe0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
11ff0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12000 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
12010 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
12020 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
12030 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
12040 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
12050 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
12060 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
12070 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
12080 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
12090 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
120a0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
120b0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
120c0 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
120d0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
120e0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
120f0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
12100 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
12110 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
12120 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
12130 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
12140 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
12150 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
12160 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
12170 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
12180 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
12190 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
121a0 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
121b0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
121c0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
121d0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
121e0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
121f0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
12200 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
12210 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
12220 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
12230 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
12240 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
12250 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
12260 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12270 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
12280 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
12290 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
122a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
122b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
122c0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
122d0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
122e0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
122f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
12300 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12310 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
12320 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
12330 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
12340 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
12350 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
12360 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
12370 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
12380 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
12390 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
123a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
123b0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
123c0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
123d0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
123e0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
123f0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
12400 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
12410 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
12420 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
12430 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12440 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
12450 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
12460 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
12470 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
12480 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
12490 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
124a0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
124b0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
124c0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
124d0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
124e0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
124f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12500 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
12510 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
12520 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
12530 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
12540 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
12550 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
12560 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
12570 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
12580 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
12590 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
125a0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
125b0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
125c0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
125d0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
125e0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
125f0 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
12600 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
12610 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
12620 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
12630 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
12640 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
12650 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
12660 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
12670 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
12680 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
12690 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
126a0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
126b0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
126c0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
126d0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
126e0 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
126f0 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
12700 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
12710 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
12720 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12730 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
12740 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
12750 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
12760 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
12770 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
12780 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
12790 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
127a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
127b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
127c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
127d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
127e0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
127f0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
12800 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
12810 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
12820 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
12830 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
12840 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
12850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
12860 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
12870 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
12880 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
12890 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
128a0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
128b0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
128c0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
128d0 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
128e0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
128f0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
12900 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
12910 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52  g. {END}.**.** R
12920 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
12930 5b 48 31 37 34 30 33 5d 20 5b 48 31 37 34 30 36  [H17403] [H17406
12940 5d 20 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68  ] [H17407].*/.ch
12950 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
12960 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
12970 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
12980 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
12990 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
129a0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
129b0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
129c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
129d0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
129e0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
129f0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
12a00 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53  stem {H17300} <S
12a10 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
12a20 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
12a30 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
12a40 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
12a50 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
12a60 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
12a70 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
12a80 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
12a90 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
12aa0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
12ab0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
12ac0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
12ad0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
12ae0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
12af0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
12b00 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
12b10 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
12b20 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
12b30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c   The sqlite3_mal
12b40 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
12b50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
12b60 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
12b70 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
12b80 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
12b90 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
12ba0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
12bb0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
12bc0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
12bd0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
12be0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
12bf0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
12c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
12c10 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
12c20 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
12c30 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
12c40 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
12c50 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
12c60 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
12c70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
12c80 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c  *.** Calling sql
12c90 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
12ca0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
12cb0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
12cc0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
12cd0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
12ce0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
12cf0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
12d00 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
12d10 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
12d20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
12d30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
12d40 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
12d50 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
12d60 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
12d70 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
12d80 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
12d90 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
12da0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
12db0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
12dc0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
12dd0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
12de0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
12df0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
12e00 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
12e10 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
12e20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
12e30 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
12e40 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
12e50 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
12e60 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
12e70 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
12e80 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
12e90 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
12ea0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
12eb0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
12ec0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
12ed0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
12ee0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
12ef0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12f00 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
12f10 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  loc()..**.** The
12f20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
12f30 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
12f40 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
12f50 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
12f60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
12f70 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
12f80 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
12f90 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
12fa0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
12fb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12fc0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
12fd0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
12fe0 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
12ff0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13000 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13010 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
13020 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
13030 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
13040 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
13050 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
13060 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
13070 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
13080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
13090 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
130a0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
130b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
130c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
130d0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
130e0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
130f0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
13100 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
13110 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
13120 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
13130 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
13140 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
13150 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
13160 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
13170 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
13180 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
13190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
131a0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
131b0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
131c0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
131d0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
131e0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
131f0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
13200 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
13210 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
13220 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
13230 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
13240 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
13250 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
13260 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
13270 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
13280 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
13290 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
132a0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
132b0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
132c0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
132d0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
132e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
132f0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
13300 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
13310 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
13320 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13330 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
13340 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
13350 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
13360 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
13370 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
13380 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
13390 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
133a0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
133b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
133c0 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
133d0 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
133e0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
133f0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13400 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13410 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d  ary..** {H17382}
13420 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
13430 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13440 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
13450 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
13460 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
13470 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
13480 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
13490 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
134a0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
134b0 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
134c0 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
134d0 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
134e0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
134f0 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
13500 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
13510 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
13520 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13530 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
13540 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
13550 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
13560 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
13570 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
13580 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
13590 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
135a0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
135b0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
135c0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
135d0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
135e0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
135f0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
13600 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
13610 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
13620 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
13630 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
13640 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
13650 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
13660 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
13670 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
13680 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
13690 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
136a0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
136b0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
136c0 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
136d0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
136e0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
136f0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
13700 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
13710 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
13720 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
13730 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
13740 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
13750 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
13760 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
13770 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
13780 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
13790 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
137a0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
137b0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
137c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
137d0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
137e0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
137f0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
13800 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
13810 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  EM]..**.** Requi
13820 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
13830 33 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48  303] [H17304] [H
13840 31 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20  17305] [H17306] 
13850 5b 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32  [H17310] [H17312
13860 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33  ] [H17315] [H173
13870 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20  18].** [H17321] 
13880 5b 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33  [H17322] [H17323
13890 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ].**.** The poin
138a0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
138b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
138c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
138d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
138e0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
138f0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
13900 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
13910 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
13920 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
13930 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
13940 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13950 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
13960 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
13970 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
13980 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
13990 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
139a0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
139b0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
139c0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
139d0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
139e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
139f0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
13a00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
13a10 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
13a20 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
13a30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
13a40 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
13a50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
13a60 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
13a70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
13a80 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
13a90 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37  tatistics {H1737
13aa0 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a  0} <S30210>.**.*
13ab0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
13ac0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
13ad0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
13ae0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
13af0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
13b00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
13b10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13b20 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
13b30 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
13b40 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
13b50 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
13b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13b70 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
13b80 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
13b90 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48 31  .** [H17371] [H1
13ba0 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b  7373] [H17374] [
13bb0 48 31 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74  H17375].*/.sqlit
13bc0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
13bd0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
13be0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
13bf0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
13c00 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
13c10 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
13c20 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
13c30 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
13c40 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33   Generator {H173
13c50 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  90} <S20000>.**.
13c60 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
13c70 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
13c80 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
13c90 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
13ca0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
13cb0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
13cc0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
13cd0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
13ce0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
13cf0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
13d00 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
13d10 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
13d20 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
13d30 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
13d40 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
13d50 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
13d60 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
13d70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
13d80 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
13d90 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
13da0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
13db0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
13dc0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
13dd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
13de0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
13df0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
13e00 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
13e10 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
13e20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
13e30 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
13e40 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
13e50 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
13e60 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
13e70 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
13e80 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
13e90 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
13ea0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
13eb0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
13ec0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
13ed0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
13ee0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
13ef0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
13f00 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
13f10 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
13f20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
13f30 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
13f40 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
13f50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13f60 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
13f70 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
13f80 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
13f90 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76  ** [H17392].*/.v
13fa0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
13fb0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
13fc0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
13fd0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
13fe0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
13ff0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
14000 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
14010 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
14020 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
14030 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14040 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
14050 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
14060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
14070 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
14080 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
14090 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
140a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
140b0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
140c0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
140d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
140e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
140f0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
14100 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
14110 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
14120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14130 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
14140 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
14150 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
14160 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
14170 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
14180 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
14190 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
141a0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
141b0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
141c0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
141d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
141e0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
141f0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
14200 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
14210 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14220 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
14230 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
14240 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
14250 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
14260 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
14270 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
14280 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
14290 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
142a0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
142b0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
142c0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
142d0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
142e0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
142f0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
14300 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
14310 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
14320 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14330 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
14340 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
14350 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
14360 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
14370 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
14380 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
14390 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
143a0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
143b0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
143c0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
143d0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
143e0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
143f0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
14400 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
14410 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
14420 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
14430 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
14440 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
14450 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
14460 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
14470 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
14480 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14490 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
144a0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
144b0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
144c0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
144d0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
144e0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
144f0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
14500 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
14510 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54  denied. .**.** T
14520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14530 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
14540 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
14550 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
14560 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
14570 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
14580 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
14590 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65  ) interface. The
145a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
145b0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
145c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
145d0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
145e0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
145f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
14600 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
14610 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
14620 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69  horized. The thi
14630 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
14640 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
14650 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
14660 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
14670 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14680 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
14690 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
146a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
146b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
146c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 63  .**.** If the ac
146d0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
146e0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
146f0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
14700 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
14710 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
14720 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
14730 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
14740 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
14750 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
14760 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
14770 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
14780 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
14790 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
147a0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
147b0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
147c0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
147d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
147e0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
147f0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
14800 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
14810 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
14820 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
14830 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 49  of a table..** I
14840 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
14850 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
14860 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
14870 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
14880 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
14890 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
148a0 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
148b0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
148c0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
148d0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
148e0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
148f0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
14900 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
14910 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
14920 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
14930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
14940 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
14950 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
14960 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
14970 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
14980 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
14990 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
149a0 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
149b0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
149c0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
149d0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
149e0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
149f0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
14a00 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
14a10 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
14a20 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
14a30 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
14a40 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
14a50 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
14a60 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
14a70 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
14a80 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
14a90 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
14aa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
14ab0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
14ac0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
14ad0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
14ae0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
14af0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
14b00 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
14b10 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
14b20 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
14b30 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
14b40 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
14b50 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
14b60 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
14b70 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
14b80 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
14b90 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
14ba0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
14bb0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
14bc0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
14bd0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
14be0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
14bf0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
14c00 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
14c10 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
14c20 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
14c30 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
14c40 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
14c50 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
14c60 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
14c70 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
14c80 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
14c90 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
14ca0 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
14cb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
14cc0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
14cd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ce0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
14cf0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
14d00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
14d10 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
14d20 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
14d30 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
14d40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
14d50 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
14d60 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
14d70 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
14d80 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
14d90 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
14da0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
14db0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
14dc0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
14dd0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
14de0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
14df0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
14e00 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
14e10 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
14e20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
14e30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14e40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
14e50 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
14e60 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
14e70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
14e80 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
14e90 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
14ea0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
14eb0 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74  *.** When [sqlit
14ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14ed0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
14ee0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
14ef0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
14f00 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65  t might be repre
14f10 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
14f20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
14f30 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
14f40 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
14f50 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
14f60 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
14f70 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
14f80 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
14f90 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
14fa0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
14fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
14fc0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  p()]..**.** Note
14fd0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
14fe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
14ff0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
15000 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
15010 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
15020 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
15030 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
15040 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
15050 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
15060 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
15070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
15080 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
15090 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
150a0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
150b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
150c0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
150d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
150e0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
150f0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
15100 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
15110 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
15120 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b  s:.** [H12501] [
15130 48 31 32 35 30 32 5d 20 5b 48 31 32 35 30 33 5d  H12502] [H12503]
15140 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 32 35 30   [H12504] [H1250
15150 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48 31 32  5] [H12506] [H12
15160 35 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a  507] [H12510].**
15170 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 32 35 31   [H12511] [H1251
15180 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48 31 32  2] [H12520] [H12
15190 35 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f  521] [H12522].*/
151a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
151b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
151c0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
151d0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
151e0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
151f0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
15200 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
15210 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
15220 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
15230 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
15240 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
15250 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35  s {H12590} <H125
15260 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
15270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
15280 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
15290 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
152a0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
152b0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
152c0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
152d0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
152e0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
152f0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
15300 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
15310 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
15320 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
15330 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15340 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
15350 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
15360 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
15370 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
15380 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
15390 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
153a0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
153b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
153c0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
153d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
153e0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
153f0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
15400 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
15410 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
15420 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15430 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
15440 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32  ction Codes {H12
15450 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a  550} <H12500>.**
15460 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
15470 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
15480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
15490 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
154a0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
154b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
154c0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
154d0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
154e0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
154f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
15500 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
15510 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
15520 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
15530 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
15540 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
15550 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
15560 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
15570 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
15580 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
15590 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
155a0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
155b0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
155c0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
155d0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
155e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
155f0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
15600 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
15610 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
15620 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
15630 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
15640 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
15650 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
15660 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
15670 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
15680 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
15690 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
156a0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
156b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
156c0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
156d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
156e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
156f0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
15700 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
15710 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20  if applicable.  
15720 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
15730 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
15740 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
15750 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
15760 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
15770 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
15780 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
15790 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
157a0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
157b0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
157c0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
157d0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
157e0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
157f0 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
15800 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35  ments:.** [H1255
15810 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48 31 32  1] [H12552] [H12
15820 35 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f  553] [H12554].*/
15830 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
15840 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
15860 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
15870 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
15880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15890 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
158a0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
158b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
158c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
158d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
158e0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
158f0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
15900 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
15910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15930 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
15940 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
15950 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
15960 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15970 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
15980 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
15990 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
159a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
159b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
159c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
159d0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
159e0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
159f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
15a00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15a10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
15a20 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
15a30 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
15a40 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
15a50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15a60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
15a70 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
15a80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
15a90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
15aa0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15ab0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
15ac0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
15ad0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
15ae0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15af0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15b00 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
15b10 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
15b20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15b30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15b40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15b50 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
15b60 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
15b70 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
15b80 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15b90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15ba0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
15bb0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
15bc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
15bd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15be0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15bf0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
15c00 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
15c10 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
15c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c40 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
15c50 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
15c60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15c70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15c90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
15ca0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
15cb0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
15cc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
15cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15ce0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
15cf0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
15d00 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
15d10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15d30 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
15d40 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
15d50 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
15d60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15d80 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
15d90 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
15da0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
15db0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
15dd0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
15de0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
15df0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
15e00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
15e20 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
15e30 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
15e40 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
15e50 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
15e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15e80 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
15e90 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
15ea0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
15eb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
15ec0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
15ed0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
15ee0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
15ef0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15f00 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
15f10 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
15f20 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
15f30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
15f40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15f50 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
15f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
15f70 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15f80 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
15f90 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15fa0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
15fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
15fc0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
15fd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15fe0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15ff0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
16000 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
16010 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
16020 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
16030 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16040 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
16050 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
16060 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
16070 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
16080 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16090 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
160a0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
160b0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
160c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
160d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
160e0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
160f0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
16100 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16110 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16130 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
16140 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
16150 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16160 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
16170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16180 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
16190 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
161a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
161b0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
161c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
161d0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
161e0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
161f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
16200 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
16210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16220 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
16230 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
16240 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
16250 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
16260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16270 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
16280 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
16290 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
162a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
162b0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
162c0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ling Functions {
162d0 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e  H12280} <S60400>
162e0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
162f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
16300 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
16310 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
16320 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
16330 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
16340 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
16350 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
16360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
16370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
16380 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
16390 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
163a0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
163b0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
163c0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
163d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
163e0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
163f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16400 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
16410 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d  k returns a UTF-
16420 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
16430 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16440 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20   text.** as the 
16450 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
16460 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
16470 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61  .  Additional ca
16480 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a  llbacks occur.**
16490 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
164a0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
164b0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
164c0 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
164d0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
164e0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
164f0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
16500 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
16510 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
16520 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
16530 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
16540 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
16550 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
16560 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
16570 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65  t finishes.  The
16580 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
16590 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
165a0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
165b0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
165c0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
165d0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
165e0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
165f0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
16600 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65  to run..**.** Re
16610 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
16620 48 31 32 32 38 31 5d 20 5b 48 31 32 32 38 32 5d  H12281] [H12282]
16630 20 5b 48 31 32 32 38 33 5d 20 5b 48 31 32 32 38   [H12283] [H1228
16640 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48 31 32  4] [H12285] [H12
16650 32 38 37 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48  287] [H12288] [H
16660 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39  12289].** [H1229
16670 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  0].*/.SQLITE_EXP
16680 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
16690 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
166a0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
166b0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
166c0 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
166d0 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
166e0 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
166f0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
16700 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
16710 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
16720 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
16730 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
16740 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
16750 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
16760 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ess Callbacks {H
16770 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12910} <S60400>.
16780 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
16790 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
167a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
167b0 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
167c0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
167d0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
167e0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
167f0 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
16800 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
16810 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
16820 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
16830 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
16840 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e  et_table()].  An
16850 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
16860 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
16870 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
16880 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
16890 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
168a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
168b0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
168c0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
168d0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
168e0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
168f0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
16900 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
16910 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
16920 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
16930 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
16940 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
16950 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
16960 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
16970 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
16980 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
16990 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
169a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
169b0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
169c0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
169d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
169e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
169f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
16a00 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
16a10 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
16a20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
16a30 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
16a40 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
16a50 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
16a60 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
16a70 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b  s:.** [H12911] [
16a80 48 31 32 39 31 32 5d 20 5b 48 31 32 39 31 33 5d  H12912] [H12913]
16a90 20 5b 48 31 32 39 31 34 5d 20 5b 48 31 32 39 31   [H12914] [H1291
16aa0 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48 31 32  5] [H12916] [H12
16ab0 39 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a  917] [H12918].**
16ac0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
16ad0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
16ae0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
16af0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
16b00 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
16b10 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
16b20 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
16b30 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37  Connection {H127
16b40 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  00} <S40200>.**.
16b50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
16b60 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
16b70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
16b80 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
16b90 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
16ba0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
16bb0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
16bc0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
16bd0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
16be0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
16bf0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
16c00 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
16c10 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
16c20 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
16c30 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
16c40 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74  open16(). A [dat
16c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16c60 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
16c70 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
16c80 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
16c90 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
16ca0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
16cb0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
16cc0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
16cd0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
16ce0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
16cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
16d00 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
16d10 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
16d20 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
16d30 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
16d40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16d50 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20  ].** object. If 
16d60 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
16d70 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
16d80 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
16d90 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
16da0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
16db0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
16dc0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
16dd0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
16de0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
16df0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
16e00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
16e10 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
16e20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
16e30 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
16e40 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
16e50 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
16e60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
16e70 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
16e80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
16e90 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
16ea0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
16eb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
16ec0 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
16ed0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
16ee0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
16ef0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
16f00 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
16f10 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
16f20 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
16f30 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
16f40 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
16f50 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
16f60 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
16f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16f80 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
16f90 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
16fa0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
16fb0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
16fc0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
16fd0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
16fe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
16ff0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
17000 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
17010 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
17020 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
17030 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
17040 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
17050 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
17060 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
17070 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
17080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17090 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
170a0 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20  ameter can take 
170b0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
170c0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
170d0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
170e0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
170f0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
17100 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20  PEN_NOMUTEX] or 
17110 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
17120 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a  LMUTEX] flags:.*
17130 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
17140 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
17150 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
17160 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
17170 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
17180 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
17190 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
171a0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
171b0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
171c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
171d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
171e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
171f0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
17200 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
17210 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
17220 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
17230 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
17240 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
17250 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
17260 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
17270 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
17280 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
17290 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
172a0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
172b0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
172c0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
172d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
172e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
172f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
17300 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
17310 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
17320 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
17330 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
17340 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
17350 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
17360 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
17370 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
17380 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
17390 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
173a0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
173b0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
173c0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
173d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
173e0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  /dd>.** </dl>.**
173f0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
17400 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
17410 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
17420 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
17430 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
17440 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
17450 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
17460 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
17470 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
17480 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
17490 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
174a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
174b0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a  LLMUTEX] flags,.
174c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
174d0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
174e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
174f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
17500 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
17510 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
17520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17530 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
17540 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
17550 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
17560 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
17570 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
17580 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
17590 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
175a0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
175b0 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53  e.  If the.** [S
175c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
175d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
175e0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
175f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
17600 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
17610 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
17620 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
17630 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
17640 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
17650 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
17660 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
17670 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  art-time..**.** 
17680 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
17690 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
176a0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
176b0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
176c0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
176d0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
176e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
176f0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
17700 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
17710 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17730 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
17740 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
17750 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
17760 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
17770 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
17780 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
17790 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
177a0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
177b0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
177c0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
177d0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
177e0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
177f0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
17800 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
17810 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
17820 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
17830 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
17840 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
17850 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
17860 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
17870 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
17880 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
17890 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
178a0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
178b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
178c0 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
178d0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
178e0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
178f0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
17900 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
17910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17920 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
17930 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
17940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
17950 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
17960 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
17970 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
17980 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
17990 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
179a0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
179b0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
179c0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
179d0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
179e0 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
179f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
17a00 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
17a10 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
17a20 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
17a30 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
17a40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
17a50 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
17a60 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
17a70 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
17a80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
17a90 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
17aa0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
17ab0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
17ac0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
17ad0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
17ae0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
17af0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
17b00 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
17b10 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
17b20 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
17b30 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
17b40 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
17b50 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
17b60 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
17b70 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
17b80 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
17b90 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
17ba0 0a 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31  .** [H12701] [H1
17bb0 32 37 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b  2702] [H12703] [
17bc0 48 31 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d  H12704] [H12706]
17bd0 20 5b 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30   [H12707] [H1270
17be0 39 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b  9] [H12711].** [
17bf0 48 31 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d  H12712] [H12713]
17c00 20 5b 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31   [H12714] [H1271
17c10 37 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32  7] [H12719] [H12
17c20 37 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f  721] [H12723].*/
17c30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
17c40 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
17c50 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
17c60 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
17c70 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
17c80 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
17c90 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
17ca0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
17cb0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
17cc0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
17cd0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
17ce0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
17cf0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
17d00 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
17d10 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
17d20 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
17d30 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
17d40 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
17d50 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
17d60 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
17d70 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
17d80 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
17d90 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
17da0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
17db0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
17dc0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
17dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
17de0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
17df0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
17e00 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
17e10 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
17e20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
17e30 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
17e40 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20  es And Messages 
17e50 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30  {H12800} <S60200
17e60 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
17e70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
17e80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17e90 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
17ea0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
17eb0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
17ec0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
17ed0 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
17ee0 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
17ef0 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
17f00 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
17f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
17f20 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
17f30 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
17f40 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
17f50 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
17f60 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
17f70 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
17f80 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
17f90 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
17fa0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
17fb0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
17fc0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
17fd0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
17fe0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
17ff0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
18000 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
18010 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
18020 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
18030 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
18040 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  abled..**.** The
18050 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
18060 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
18070 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
18080 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
18090 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
180a0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
180b0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
180c0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
180d0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
180e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
180f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
18100 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
18110 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
18120 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
18130 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
18140 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
18150 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
18160 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
18170 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
18180 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
18190 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
181a0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
181b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
181c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
181d0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
181e0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
181f0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
18200 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
18210 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
18220 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
18230 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
18240 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
18250 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
18260 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
18270 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
18280 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
18290 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
182a0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
182b0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
182c0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
182d0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
182e0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
182f0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
18300 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
18310 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
18320 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
18330 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
18340 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
18350 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
18360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18370 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
18380 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
18390 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
183a0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
183b0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
183c0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
183d0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
183e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
183f0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
18400 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
18410 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
18420 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
18430 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
18440 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
18450 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
18460 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
18470 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
18480 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
18490 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
184a0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
184b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
184c0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
184d0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
184e0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
184f0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
18500 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75   set..**.** Requ
18510 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
18520 32 38 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b  2801] [H12802] [
18530 48 31 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d  H12803] [H12807]
18540 20 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30   [H12808] [H1280
18550 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
18560 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
18570 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
18580 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
18590 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
185a0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
185b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
185c0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
185d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
185e0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
185f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18600 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
18610 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20  Object {H13000} 
18620 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57  <H13010>.** KEYW
18630 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
18640 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
18650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
18660 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
18670 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
18680 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
18690 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
186a0 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
186b0 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
186c0 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
186d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
186e0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
186f0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
18700 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
18710 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
18720 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
18730 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
18740 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
18750 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
18760 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
18770 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
18780 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
18790 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
187a0 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
187b0 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
187c0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
187d0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
187e0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
187f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
18800 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
18810 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
18820 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
18830 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
18840 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
18850 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
18860 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
18870 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
18880 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
18890 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
188a0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
188b0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
188c0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
188d0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
188e0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
188f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
18900 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
18910 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
18920 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
18930 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
18940 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
18950 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
18960 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
18970 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
18980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
18990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
189a0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20  Run-time Limits 
189b0 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30  {H12760} <S20600
189c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
189d0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
189e0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
189f0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
18a00 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
18a10 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
18a20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
18a30 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
18a40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
18a50 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18a60 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
18a70 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
18a80 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
18a90 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
18aa0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
18ab0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
18ac0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
18ad0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
18ae0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
18af0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
18b00 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
18b10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
18b20 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
18b30 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68  t construct.  Th
18b40 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
18b50 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74  ns the old limit
18b60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
18b70 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
18b80 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
18b90 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
18ba0 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68  anged..** For th
18bb0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
18bc0 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
18bd0 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
18be0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
18bf0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
18c00 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
18c10 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
18c20 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
18c30 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
18c40 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
18c50 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
18c60 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
18c70 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
18c80 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65  _MAX_".).** Atte
18c90 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
18ca0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
18cb0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
18cc0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
18cd0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
18ce0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
18cf0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  limit..**.** Run
18d00 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65   time limits are
18d10 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
18d20 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
18d30 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
18d40 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
18d50 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
18d60 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
18d70 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
18d80 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
18d90 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
18da0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
18db0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
18dc0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
18dd0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
18de0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
18df0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
18e00 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
18e10 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
18e20 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
18e30 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
18e40 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
18e50 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
18e60 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
18e70 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
18e80 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
18e90 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
18ea0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
18eb0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
18ec0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
18ed0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
18ee0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
18ef0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
18f00 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
18f10 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
18f20 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
18f30 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
18f40 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
18f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
18f60 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
18f70 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
18f80 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
18f90 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
18fa0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
18fb0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
18fc0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
18fd0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
18fe0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
18ff0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
19000 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
19010 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
19020 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
19030 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
19040 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
19050 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  leases..**.** Re
19060 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
19070 48 31 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d  H12762] [H12766]
19080 20 5b 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74   [H12769].*/.int
19090 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
190a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
190b0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
190c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
190d0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
190e0 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30  tegories {H12790
190f0 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45  } <H12760>.** KE
19100 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
19110 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20  ategory} {limit 
19120 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
19130 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
19140 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
19150 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
19160 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
19170 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
19180 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
19190 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
191a0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
191b0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
191c0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
191d0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
191e0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
191f0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
19200 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
19210 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
19220 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
19230 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
19240 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
19250 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
19260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
19270 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
19280 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
19290 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ow.<dd>.**.** <d
192a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
192b0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
192c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
192d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
192e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
192f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19300 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
19310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19320 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
19330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
19340 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
19350 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
19360 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
19370 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
19380 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
19390 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
193a0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
193b0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
193c0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
193d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
193e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
193f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
19400 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
19410 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
19420 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
19430 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
19440 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
19450 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
19460 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
19470 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
19480 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
19490 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
194a0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
194b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
194c0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
194d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
194e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
194f0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
19500 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
19510 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
19520 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
19530 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19550 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
19560 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
19570 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
19580 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
19590 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
195a0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
195b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
195c0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
195d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
195e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
195f0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
19600 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e  databases].</dd>
19610 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19620 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
19630 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
19640 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
19650 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
19660 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
19670 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
19680 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
19690 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
196a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
196b0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
196c0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
196d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
196e0 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
196f0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
19700 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
19710 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
19720 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
19730 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
19740 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
19750 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
19760 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
19770 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
19780 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
19790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
197a0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
197b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
197c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
197d0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
197e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
197f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
19800 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
19810 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
19820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19830 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
19840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19850 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
19860 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
19870 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
19880 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
19890 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
198a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
198b0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
198c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
198d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
198e0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
198f0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
19900 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
19910 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
19920 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
19930 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
19940 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30  t {H13010} <S100
19950 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
19960 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
19970 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
19980 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
19990 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
199a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
199b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
199c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
199d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
199e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
199f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
19a00 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
19a10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19a20 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
19a30 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
19a40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
19a50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
19a60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
19a70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
19a80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19a90 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
19aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
19ab0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
19ac0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
19ad0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19ae0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
19af0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
19b00 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
19b10 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
19b20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
19b30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
19b40 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
19b50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19b60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
19b70 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
19b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
19b90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
19ba0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
19bb0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
19bc0 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  * If the nByte a
19bd0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
19be0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
19bf0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
19c00 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
19c10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
19c20 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e   If nByte is non
19c30 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
19c40 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
19c50 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
19c60 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
19c70 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74  zSql.  When nByt
19c80 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
19c90 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
19ca0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
19cb0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
19cc0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
19cd0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
19ce0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
19cf0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
19d00 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
19d10 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
19d20 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
19d30 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
19d40 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
19d50 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
19d60 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
19d70 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
19d80 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
19d90 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
19da0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
19db0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
19dc0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
19dd0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
19de0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
19df0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
19e00 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
19e10 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61  s..**.** If pzTa
19e20 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
19e30 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
19e40 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
19e50 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
19e60 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
19e70 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
19e80 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
19e90 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
19ea0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
19eb0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
19ec0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
19ed0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
19ee0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
19ef0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
19f00 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
19f10 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
19f20 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
19f30 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
19f40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19f50 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
19f60 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
19f70 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66  te3_step()].  If
19f80 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
19f90 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
19fa0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
19fb0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
19fc0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
19fd0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
19fe0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
19ff0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
1a000 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
1a010 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
1a020 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
1a030 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1a040 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1a050 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1a060 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1a070 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1a080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1a090 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1a0a0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1a0b0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
1a0c0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f  be NULL..**.** O
1a0d0 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
1a0e0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1a0f0 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  ed, otherwise an
1a100 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1a110 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1a120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1a130 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
1a140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a150 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
1a160 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
1a170 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
1a180 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
1a190 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
1a1a0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
1a1b0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
1a1c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
1a1d0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
1a1e0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
1a1f0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1a200 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1a210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1a220 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1a230 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1a240 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1a250 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1a260 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1a270 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1a280 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1a290 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1a2a0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1a2b0 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c  ave a differentl
1a2c0 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a  y in two ways:.*
1a2d0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1a2e0 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  >.** If the data
1a2f0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
1a300 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
1a310 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
1a320 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
1a330 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
1a340 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
1a350 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
1a360 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1a370 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
1a380 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
1a390 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
1a3a0 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61  .  If the schema
1a3b0 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a   has changed in.
1a3c0 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61  ** a way that ma
1a3d0 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e  kes the statemen
1a3e0 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69  t no longer vali
1a3f0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  d, [sqlite3_step
1a400 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a  ()] will still.*
1a410 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1a420 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75  _SCHEMA].  But u
1a430 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79  nlike the legacy
1a440 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49   behavior, [SQLI
1a450 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a  TE_SCHEMA] is.**
1a460 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72   now a fatal err
1a470 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71  or.  Calling [sq
1a480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a490 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
1a4a0 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
1a4b0 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e  rror go away.  N
1a4c0 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65  ote: use [sqlite
1a4d0 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66  3_errmsg()] to f
1a4e0 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20  ind the text.** 
1a4f0 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65  of the parsing e
1a500 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74  rror that result
1a510 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  s in an [SQLITE_
1a520 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a  SCHEMA] return..
1a530 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1a540 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65  li>.** When an e
1a550 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1a560 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1a570 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1a580 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1a590 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1a5a0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1a5b0 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c  r codes].  The l
1a5c0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
1a5d0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
1a5e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
1a5f0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
1a600 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
1a610 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
1a620 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f  de.** and you wo
1a630 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1a640 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1a650 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1a660 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  ()] in order.** 
1a670 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1a680 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1a690 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1a6a0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1a6b0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1a6c0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1a6d0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1a6e0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1a6f0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1a700 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1a710 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1a720 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d  nts:.** [H13011]
1a730 20 5b 48 31 33 30 31 32 5d 20 5b 48 31 33 30 31   [H13012] [H1301
1a740 33 5d 20 5b 48 31 33 30 31 34 5d 20 5b 48 31 33  3] [H13014] [H13
1a750 30 31 35 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48  015] [H13016] [H
1a760 31 33 30 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a  13019] [H13021].
1a770 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  **.*/.int sqlite
1a780 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
1a790 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1a7a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1a7b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a7c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1a7d0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1a7e0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1a7f0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1a800 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1a810 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1a820 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a830 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a840 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a850 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a860 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a870 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1a880 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a890 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a8a0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a8b0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1a8c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a8d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a8e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a8f0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a900 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1a910 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a920 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a930 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1a940 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1a950 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1a960 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1a970 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1a980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1a990 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1a9a0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1a9b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a9c0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1a9d0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1a9e0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1a9f0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1aa00 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1aa10 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
1aa20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1aa30 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1aa40 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1aa50 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1aa60 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1aa70 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1aa80 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1aa90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1aaa0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1aab0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1aac0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1aad0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1aae0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1aaf0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ab00 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1ab10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1ab20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1ab30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1ab40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ab50 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
1ab60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ab70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1ab80 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1ab90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1aba0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1abb0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1abc0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1abd0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1abe0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1abf0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1ac00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1ac10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1ac20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1ac30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1ac40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1ac50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1ac60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1ac70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1ac80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
1ac90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1aca0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1acb0 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d  ent SQL {H13100}
1acc0 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H13000>.**.** 
1acd0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1ace0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1acf0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1ad00 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1ad10 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1ad20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1ad30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ad40 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1ad50 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1ad60 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1ad70 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1ad80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1ad90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ada0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  6_v2()]..**.** R
1adb0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1adc0 5b 48 31 33 31 30 31 5d 20 5b 48 31 33 31 30 32  [H13101] [H13102
1add0 5d 20 5b 48 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f  ] [H13103].*/.co
1ade0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1adf0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1ae00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1ae10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1ae20 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1ae30 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35  alue Object {H15
1ae40 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  000} <S20200>.**
1ae50 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
1ae60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ae70 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
1ae80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1ae90 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1aea0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
1aeb0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
1aec0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
1aed0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
1aee0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
1aef0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
1af00 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
1af10 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
1af20 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
1af30 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74  tores. Values st
1af40 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1af50 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
1af60 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
1af70 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
1af80 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
1af90 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
1afa0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
1afb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1afc0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
1afd0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
1afe0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
1aff0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
1b000 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
1b010 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1b020 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
1b030 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
1b040 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
1b050 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
1b060 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1b070 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
1b080 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
1b090 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
1b0a0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
1b0b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
1b0c0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1b0d0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1b0e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1b0f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1b100 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1b110 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1b120 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1b130 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1b140 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1b150 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1b160 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1b170 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1b180 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1b190 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1b1a0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1b1b0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1b1c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1b1d0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1b1e0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1b1f0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1b200 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
1b210 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
1b220 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
1b230 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
1b240 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
1b250 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
1b260 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
1b270 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
1b280 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1b290 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
1b2a0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1b2b0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
1b2c0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1b2d0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1b2e0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1b2f0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1b300 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1b310 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1b320 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
1b330 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
1b340 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
1b350 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1b360 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
1b370 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1b380 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
1b390 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
1b3a0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1b3b0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1b3c0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1b3d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1b3e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1b3f0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
1b400 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
1b410 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b420 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
1b430 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
1b440 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
1b450 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
1b460 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
1b470 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1b480 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
1b490 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
1b4a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1b4b0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1b4c0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1b4d0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1b4e0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1b4f0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1b500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1b510 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1b520 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1b530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1b540 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1b550 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1b560 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1b570 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1b580 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1b590 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1b5a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1b5b0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1b5c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1b5d0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1b5e0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1b5f0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1b600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1b610 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1b620 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30  xt Object {H1600
1b630 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  1} <S20200>.**.*
1b640 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1b650 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1b660 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1b670 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1b680 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1b690 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f  xt object.  A po
1b6a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
1b6b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1b6c0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
1b6d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b6e0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
1b6f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1b700 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
1b710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1b720 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
1b730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
1b740 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
1b750 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
1b760 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
1b770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
1b780 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
1b790 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
1b7a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
1b7b0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
1b7c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
1b7d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
1b7e0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
1b7f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
1b800 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
1b810 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
1b820 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
1b830 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b840 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1b850 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1b860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b870 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
1b880 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
1b890 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30  atements {H13500
1b8a0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45  } <S70300>.** KE
1b8b0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
1b8c0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
1b8d0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
1b8e0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
1b8f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1b900 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
1b910 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
1b920 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
1b930 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  g}.**.** In the 
1b940 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75  SQL strings inpu
1b950 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1b960 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1b970 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
1b980 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1b990 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
1b9a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 6f 6e  parameter] in on
1b9b0 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  e of these forms
1b9c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1b9d0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1b9e0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1b9f0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1ba00 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1ba10 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1ba20 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
1ba30 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
1ba40 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
1ba50 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1ba60 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c  and VVV is an al
1ba70 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
1ba80 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20  meter name. The 
1ba90 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
1baa0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
1bab0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
1bac0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
1bad0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
1bae0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1baf0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1bb00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1bb10 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1bb20 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1bb30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1bb40 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1bb50 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1bb60 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
1bb70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1bb80 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1bb90 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1bba0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1bbb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1bbc0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
1bbd0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1bbe0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1bbf0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1bc00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1bc10 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74  set..** The left
1bc20 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
1bc30 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
1bc40 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
1bc50 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
1bc60 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
1bc70 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
1bc80 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
1bc90 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
1bca0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
1bcb0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
1bcc0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1bcd0 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64  ence..** The ind
1bce0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1bcf0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1bd00 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1bd10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1bd20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1bd30 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
1bd40 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
1bd50 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
1bd60 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
1bd70 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
1bd80 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
1bd90 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1bda0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
1bdb0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1bdc0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
1bdd0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1bde0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
1bdf0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
1be00 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
1be10 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
1be20 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
1be30 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1be40 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f  *.** In those ro
1be50 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1be60 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1be70 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1be80 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1be90 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
1bea0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1beb0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1bec0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1bed0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
1bee0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
1bef0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1bf00 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
1bf10 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
1bf20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1bf30 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1bf40 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1bf50 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1bf60 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1bf70 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1bf80 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1bf90 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
1bfa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1bfb0 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
1bfc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
1bfd0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
1bfe0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
1bff0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
1c000 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
1c010 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
1c020 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
1c030 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
1c040 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
1c050 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1c060 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
1c070 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
1c080 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
1c090 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
1c0a0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
1c0b0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
1c0c0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
1c0d0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
1c0e0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
1c0f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
1c100 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
1c110 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
1c120 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
1c130 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
1c140 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
1c150 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
1c160 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
1c170 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
1c180 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1c190 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
1c1a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c1b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
1c1c0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
1c1d0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
1c1e0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
1c1f0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
1c200 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  .  A zeroblob us
1c210 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1c220 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1c230 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1c240 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1c250 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1c260 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1c270 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1c280 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1c290 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1c2a0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1c2b0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1c2c0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1c2d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1c2e0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1c2f0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1c300 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41  ] routines..** A
1c310 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
1c320 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
1c330 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
1c340 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
1c350 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c360 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1c370 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
1c380 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
1c390 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c3a0 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
1c3b0 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
1c3c0 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
1c3d0 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
1c3e0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
1c3f0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
1c400 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
1c410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1c420 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
1c430 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
1c440 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
1c450 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
1c460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1c470 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1c480 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
1c490 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
1c4a0 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
1c4b0 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
1c4c0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
1c4d0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
1c4e0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
1c4f0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
1c500 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
1c510 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
1c520 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
1c530 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
1c540 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
1c550 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
1c560 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
1c570 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
1c580 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
1c590 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
1c5a0 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
1c5b0 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
1c5c0 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
1c5d0 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
1c5e0 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
1c5f0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
1c600 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
1c610 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
1c620 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
1c630 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
1c640 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
1c650 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
1c660 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
1c670 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
1c680 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1c690 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
1c6a0 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
1c6b0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
1c6c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c6d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c6e0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1c6f0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1c700 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1c710 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
1c720 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c730 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1c740 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1c750 0a 2a 2a 20 5b 48 31 33 35 30 36 5d 20 5b 48 31  .** [H13506] [H1
1c760 33 35 30 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b  3509] [H13512] [
1c770 48 31 33 35 31 35 5d 20 5b 48 31 33 35 31 38 5d  H13515] [H13518]
1c780 20 5b 48 31 33 35 32 31 5d 20 5b 48 31 33 35 32   [H13521] [H1352
1c790 34 5d 20 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b  4] [H13527].** [
1c7a0 48 31 33 35 33 30 5d 20 5b 48 31 33 35 33 33 5d  H13530] [H13533]
1c7b0 20 5b 48 31 33 35 33 36 5d 20 5b 48 31 33 35 33   [H13536] [H1353
1c7c0 39 5d 20 5b 48 31 33 35 34 32 5d 20 5b 48 31 33  9] [H13542] [H13
1c7d0 35 34 35 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48  545] [H13548] [H
1c7e0 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74  13551].**.*/.int
1c7f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1c800 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1c810 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1c820 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
1c830 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1c840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
1c850 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
1c860 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
1c870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c880 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
1c890 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
1c8a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1c8b0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
1c8c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
1c8d0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
1c8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
1c8f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c900 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1c910 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
1c920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c930 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
1c940 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1c950 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1c960 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
1c970 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c980 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1c990 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1c9a0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1c9b0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
1c9c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1c9d0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
1c9e0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
1c9f0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
1ca00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ca10 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
1ca20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1ca30 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
1ca40 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c  eters {H13600} <
1ca50 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
1ca60 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
1ca70 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
1ca80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
1ca90 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
1caa0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
1cab0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
1cac0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1cad0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1cae0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1caf0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1cb00 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1cb10 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1cb20 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
1cb30 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
1cb40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1cb50 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
1cb60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
1cb70 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
1cb80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1cb90 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
1cba0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
1cbb0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
1cbc0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
1cbd0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
1cbe0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
1cbf0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
1cc00 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
1cc10 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
1cc20 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
1cc30 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
1cc40 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73   the ?NNN are us
1cc50 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
1cc60 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
1cc70 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  list..**.** See 
1cc80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1cc90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1cca0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1ccb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1ccc0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1ccd0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1cce0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1ccf0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ex()]..**.** Req
1cd00 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1cd10 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13601].*/.int sq
1cd20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1cd30 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
1cd40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
1cd50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
1cd60 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
1cd70 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53  eter {H13620} <S
1cd80 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70300>.**.** Thi
1cd90 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1cda0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1cdb0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1cdc0 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61  -th.** [SQL para
1cdd0 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65  meter] in a [pre
1cde0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1cdf0 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
1ce00 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1ce10 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1ce20 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1ce30 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
1ce40 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
1ce50 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
1ce60 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1ce70 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1ce80 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1ce90 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1cea0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
1ceb0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
1cec0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
1ced0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
1cee0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
1cef0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1cf00 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
1cf10 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
1cf20 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
1cf30 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
1cf40 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
1cf50 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
1cf60 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  eters"..**.** Th
1cf70 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1cf80 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1cf90 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1cfa0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
1cfb0 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
1cfc0 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
1cfd0 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
1cfe0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
1cff0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
1d000 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
1d010 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
1d020 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
1d030 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
1d040 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
1d050 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
1d060 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
1d070 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
1d080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d090 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
1d0a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1d0b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1d0c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1d0d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1d0e0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1d0f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d100 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1d110 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1d120 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1d130 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ex()]..**.** Req
1d140 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1d150 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13621].*/.const 
1d160 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
1d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1d180 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1d190 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
1d1a0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
1d1b0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
1d1c0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b  h A Given Name {
1d1d0 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e  H13640} <S70300>
1d1e0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
1d1f0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
1d200 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
1d210 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65  n its name.  The
1d220 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
1d230 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
1d240 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
1d250 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
1d260 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1d270 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1d280 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
1d290 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
1d2a0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
1d2b0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
1d2c0 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61  s found.  The pa
1d2d0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
1d2e0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
1d2f0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
1d300 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1d310 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
1d320 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
1d330 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
1d340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1d350 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1d360 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1d370 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1d380 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1d390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d3a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1d3b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d3c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1d3d0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  ndex()]..**.** R
1d3e0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1d3f0 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20  [H13641].*/.int 
1d400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d410 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
1d420 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
1d430 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
1d440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d450 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
1d460 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
1d470 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
1d480 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  660} <S70300>.**
1d490 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
1d4a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
1d4b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
1d4c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
1d4d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
1d4e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d4f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
1d500 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1d510 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20  tement]..** Use 
1d520 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
1d530 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
1d540 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
1d550 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  L..**.** Require
1d560 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36  ments:.** [H1366
1d570 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  1].*/.int sqlite
1d580 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
1d590 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1d5a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d5b0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
1d5c0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
1d5d0 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
1d5e0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
1d5f0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
1d600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
1d610 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
1d620 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
1d630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d640 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
1d650 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
1d660 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
1d670 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1d680 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
1d690 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
1d6a0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
1d6b0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1d6c0 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a  ts:.** [H13711].
1d6d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1d6e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
1d6f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1d700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d710 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
1d720 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
1d730 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
1d740 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1d750 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1d760 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
1d770 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
1d780 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
1d790 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1d7a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1d7b0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
1d7c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
1d7d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
1d7e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d7f0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1d800 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1d810 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1d820 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1d830 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d840 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1d850 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1d860 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
1d870 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1d880 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1d890 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
1d8a0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
1d8b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1d8c0 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
1d8d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1d8e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
1d8f0 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
1d900 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
1d910 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
1d920 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1d930 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1d940 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1d950 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d960 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
1d970 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
1d980 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1d990 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1d9a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
1d9b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1d9c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1d9d0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
1d9e0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
1d9f0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
1da00 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
1da10 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
1da20 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
1da30 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
1da40 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
1da50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
1da60 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
1da70 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
1da80 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1da90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1daa0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
1dab0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
1dac0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
1dad0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
1dae0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
1daf0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
1db00 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
1db10 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
1db20 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
1db30 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
1db40 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
1db50 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
1db60 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
1db70 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
1db80 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  e next..**.** Re
1db90 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1dba0 48 31 33 37 32 31 5d 20 5b 48 31 33 37 32 33 5d  H13721] [H13723]
1dbb0 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 33 37 32   [H13724] [H1372
1dbc0 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48 31 33  5] [H13726] [H13
1dbd0 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  727].*/.const ch
1dbe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1dbf0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
1dc00 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
1dc10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1dc20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1dc30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dc40 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
1dc50 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
1dc60 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
1dc70 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34  ry Result {H1374
1dc80 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1dc90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dca0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
1dcb0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68   to determine wh
1dcc0 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61  at column of wha
1dcd0 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68  t.** table in wh
1dce0 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72  ich database a r
1dcf0 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45  esult of a [SELE
1dd00 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
1dd10 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
1dd20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1dd30 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
1dd40 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
1dd50 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
1dd60 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
1dd70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
1dd80 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20   The _database_ 
1dd90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
1dda0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1ddb0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
1ddc0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1ddd0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
1dde0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
1ddf0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
1de00 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
1de10 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74  name..** The ret
1de20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
1de30 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
1de40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1de50 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
1de60 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
1de70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1de80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
1de90 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
1dea0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
1deb0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
1dec0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
1ded0 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74  ** The names ret
1dee0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
1def0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
1df00 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
1df10 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
1df20 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
1df30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1df40 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66  rgument to the f
1df50 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69  ollowing calls i
1df60 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
1df70 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65  atement]..** The
1df80 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
1df90 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
1dfa0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f  about the Nth co
1dfb0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
1dfc0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
1dfd0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
1dfe0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
1dff0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
1e000 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  * If the Nth col
1e010 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
1e020 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1e030 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1e040 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
1e050 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
1e060 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
1e070 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
1e080 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
1e090 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ULL.  These rout
1e0a0 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
1e0b0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
1e0c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e0d0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
1e0e0 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74  s.  Otherwise, t
1e0f0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
1e100 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
1e110 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
1e120 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d  ble.** and colum
1e130 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
1e140 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
1e150 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
1e160 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
1e170 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
1e180 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
1e190 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
1e1a0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
1e1b0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
1e1c0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
1e1d0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
1e1e0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
1e1f0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
1e200 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
1e210 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
1e220 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1e230 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
1e240 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1e250 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
1e260 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
1e270 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31  d..**.** {A13751
1e280 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  }.** If two or m
1e290 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
1e2a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
1e2b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1e2c0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
1e2d0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
1e2e0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
1e2f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
1e300 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
1e310 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
1e320 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
1e330 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e340 37 34 31 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48  741] [H13742] [H
1e350 31 33 37 34 33 5d 20 5b 48 31 33 37 34 34 5d 20  13743] [H13744] 
1e360 5b 48 31 33 37 34 35 5d 20 5b 48 31 33 37 34 36  [H13745] [H13746
1e370 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a  ] [H13748].**.**
1e380 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
1e390 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
1e3a0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
1e3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1e3c0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
1e3d0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
1e3e0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
1e3f0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
1e400 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
1e410 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
1e420 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
1e430 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
1e440 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
1e450 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
1e460 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e470 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
1e480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e490 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1e4a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1e4b0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
1e4c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e4d0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1e4e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1e4f0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
1e500 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1e510 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1e520 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
1e530 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1e540 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
1e550 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1e560 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
1e570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e580 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1e590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1e5a0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
1e5b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e5c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e5d0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
1e5e0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
1e5f0 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53  sult {H13760} <S
1e600 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
1e610 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1e620 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
1e630 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
1e640 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
1e650 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
1e660 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
1e670 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
1e680 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
1e690 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
1e6a0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
1e6b0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
1e6c0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
1e6d0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
1e6e0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
1e6f0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
1e700 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
1e710 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74   returned.  If t
1e720 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1e730 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e740 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
1e750 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
1e760 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
1e770 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
1e780 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
1e790 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
1e7a0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
1e7b0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f  . {END}.**.** Fo
1e7c0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
1e7d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1e7e0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
1e7f0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
1e800 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
1e810 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
1e820 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1e830 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
1e840 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
1e850 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
1e860 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
1e870 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
1e880 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
1e890 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
1e8a0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
1e8b0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
1e8c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1e8d0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
1e8e0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a   column (i==0)..
1e8f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
1e900 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
1e910 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a  me typing.  So j
1e920 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
1e930 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
1e940 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
1e950 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
1e960 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
1e970 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
1e980 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
1e990 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
1e9a0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
1e9b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
1e9c0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
1e9d0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
1e9e0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
1e9f0 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61  c.  Type.** is a
1ea00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
1ea10 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
1ea20 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
1ea30 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
1ea40 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
1ea50 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  values..**.** Re
1ea60 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1ea70 48 31 33 37 36 31 5d 20 5b 48 31 33 37 36 32 5d  H13761] [H13762]
1ea80 20 5b 48 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e   [H13763].*/.con
1ea90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1eaa0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
1eab0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1eac0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1ead0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1eae0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
1eaf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
1eb00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1eb10 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
1eb20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30  Statement {H1320
1eb30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
1eb40 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
1eb50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
1eb60 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
1eb70 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
1eb80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eb90 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1eba0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ebb0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
1ebc0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1ebd0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
1ebe0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
1ebf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ec00 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
1ec10 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
1ec20 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
1ec30 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
1ec40 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
1ec50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
1ec60 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
1ec70 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
1ec80 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
1ec90 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
1eca0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
1ecb0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
1ecc0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
1ecd0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
1ece0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
1ecf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1ed00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed10 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
1ed20 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
1ed30 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
1ed40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
1ed50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1ed60 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
1ed70 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
1ed80 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
1ed90 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
1eda0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
1edb0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
1edc0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
1edd0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
1ede0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
1edf0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  *.** In the lega
1ee00 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
1ee10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
1ee20 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
1ee30 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
1ee40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
1ee50 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
1ee60 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
1ee70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
1ee80 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
1ee90 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
1eea0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
1eeb0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
1eec0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1eed0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
1eee0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
1eef0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
1ef00 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
1ef10 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
1ef20 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
1ef30 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
1ef40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
1ef50 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
1ef60 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
1ef70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1ef80 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
1ef90 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
1efa0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
1efb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1efc0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
1efd0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1efe0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
1eff0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
1f000 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
1f010 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
1f020 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1f030 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
1f040 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
1f050 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
1f060 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
1f070 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
1f080 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
1f090 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
1f0a0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
1f0b0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
1f0c0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
1f0d0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
1f0e0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
1f0f0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
1f100 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
1f110 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
1f120 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1f130 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
1f140 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
1f150 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
1f160 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
1f170 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
1f180 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
1f190 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
1f1a0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
1f1b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
1f1c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
1f1d0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
1f1e0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
1f1f0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
1f200 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
1f210 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
1f220 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
1f230 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
1f240 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
1f250 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
1f260 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
1f270 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
1f280 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
1f290 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   data..**.** [SQ
1f2a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
1f2b0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
1f2c0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
1f2d0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
1f2e0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
1f2f0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
1f300 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
1f310 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
1f320 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
1f330 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
1f340 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
1f350 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1f360 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1f370 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61  ** With the lega
1f380 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
1f390 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
1f3a0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
1f3b0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
1f3c0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
1f3d0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
1f3e0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
1f3f0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
1f400 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
1f410 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
1f420 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1f430 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1f440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
1f450 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1f460 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
1f470 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
1f480 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
1f490 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
1f4a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
1f4b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
1f4c0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
1f4d0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
1f4e0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
1f4f0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
1f500 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
1f510 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
1f520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f530 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
1f540 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
1f550 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
1f560 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
1f570 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
1f580 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f590 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
1f5a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
1f5b0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
1f5c0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
1f5d0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
1f5e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f5f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
1f600 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
1f610 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
1f620 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
1f630 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
1f640 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
1f650 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
1f660 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1f670 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
1f680 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
1f690 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
1f6a0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
1f6b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1f6c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
1f6d0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
1f6e0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
1f6f0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
1f700 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
1f710 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
1f720 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
1f730 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1f740 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
1f750 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
1f760 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
1f770 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
1f780 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
1f790 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
1f7a0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
1f7b0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
1f7c0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
1f7d0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
1f7e0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
1f7f0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
1f800 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
1f810 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
1f820 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
1f830 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1f840 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1f850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f860 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
1f870 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
1f880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f890 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f8a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
1f8b0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
1f8c0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
1f8d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
1f8e0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
1f8f0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
1f900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
1f910 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
1f920 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
1f930 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1f940 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1f950 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48  :.** [H13202] [H
1f960 31 35 33 30 34 5d 20 5b 48 31 35 33 30 36 5d 20  15304] [H15306] 
1f970 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 33 31 30  [H15308] [H15310
1f980 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1f990 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
1f9a0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1f9b0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
1f9c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
1f9d0 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30  sult set {H13770
1f9e0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1f9f0 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   Returns the num
1fa00 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e  ber of values in
1fa10 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
1fa20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
1fa30 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  et..**.** Requir
1fa40 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1fa50 37 31 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a  71] [H13772].*/.
1fa60 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
1fa70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1fa80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1fa90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
1faa0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
1fab0 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31  pes {H10265} <S1
1fac0 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a  0110><S10120>.**
1fad0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
1fae0 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_TEXT.**.** {H1
1faf0 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75  0266} Every valu
1fb00 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
1fb10 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
1fb20 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
1fb30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1fb40 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
1fb50 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
1fb60 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
1fb70 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
1fb80 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
1fb90 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
1fba0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
1fbb0 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
1fbc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1fbd0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
1fbe0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
1fbf0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
1fc00 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
1fc10 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
1fc20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
1fc30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1fc40 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
1fc50 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
1fc60 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
1fc70 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
1fc80 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
1fc90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
1fca0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
1fcb0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
1fcc0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
1fcd0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
1fce0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1fcf0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
1fd00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
1fd10 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
1fd20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
1fd30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1fd40 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
1fd50 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
1fd60 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
1fd70 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
1fd80 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
1fd90 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
1fda0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
1fdb0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
1fdc0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
1fdd0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
1fde0 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37  y {H13800} <S107
1fdf0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1fe00 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
1fe10 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
1fe20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1fe30 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
1fe40 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
1fe50 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
1fe60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1fe70 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
1fe80 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
1fe90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
1fea0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
1feb0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
1fec0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
1fed0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1fee0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
1fef0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
1ff00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1ff10 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
1ff20 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
1ff30 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
1ff40 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
1ff50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
1ff60 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
1ff70 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
1ff80 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
1ff90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1ffa0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1ffb0 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
1ffc0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
1ffd0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
1ffe0 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ned.  The leftmo
1fff0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
20000 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
20010 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a  the index 0..**.
20020 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
20030 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
20040 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
20050 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
20060 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
20070 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
20080 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
20090 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
200a0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
200b0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
200c0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
200d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
200e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
200f0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
20100 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
20110 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
20120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
20130 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
20140 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
20150 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
20160 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
20170 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
20180 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
20190 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
201a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
201b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
201c0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
201d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
201e0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
201f0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
20200 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
20210 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
20220 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20230 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
20240 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
20250 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
20260 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
20270 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
20280 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
20290 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
202a0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
202b0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
202c0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
202d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
202e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
202f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20300 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
20310 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
20320 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
20330 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
20340 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
20350 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
20360 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
20370 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
20380 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
20390 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
203a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
203b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
203c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
203d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
203e0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
203f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
20400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
20410 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
20420 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
20430 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
20440 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
20450 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
20460 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
20470 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
20480 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
20490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
204a0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
204b0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
204c0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
204d0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
204e0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
204f0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
20500 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
20510 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
20520 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
20530 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
20540 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
20550 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
20560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20570 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
20580 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
20590 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
205a0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
205b0 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
205c0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
205d0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
205e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
205f0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
20600 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
20610 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
20620 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
20630 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
20640 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
20650 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
20660 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
20670 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
20680 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
20690 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
206a0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
206b0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
206c0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
206d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
206e0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
206f0 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
20700 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
20710 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
20720 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
20730 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
20740 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
20750 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
20760 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
20770 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
20780 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
20790 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
207a0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
207b0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e  ers..**.** Strin
207c0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
207d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
207e0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
207f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
20800 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
20810 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
20820 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
20830 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
20840 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
20850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
20860 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
20870 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
20880 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
20890 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
208a0 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
208b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
208c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
208d0 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
208e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
208f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
20900 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
20910 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
20920 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
20930 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
20940 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
20950 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** The zero term
20960 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
20970 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
20980 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ount..**.** The 
20990 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
209a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
209b0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
209c0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
209d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
209e0 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
209f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20a00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
20a10 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
20a20 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
20a30 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
20a40 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
20a50 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
20a60 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
20a70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20a80 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
20a90 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
20aa0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
20ab0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
20ac0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
20ad0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
20ae0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
20af0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
20b00 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
20b10 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
20b20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
20b30 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
20b40 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
20b50 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
20b60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20b70 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
20b80 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
20b90 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
20ba0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
20bb0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
20bc0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
20bd0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
20be0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
20bf0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
20c00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20c10 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
20c20 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
20c30 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
20c40 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
20c50 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
20c60 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
20c70 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
20c80 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
20c90 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
20ca0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
20cb0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
20cc0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
20cd0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
20ce0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
20cf0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
20d00 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
20d10 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
20d20 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
20d30 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
20d40 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
20d50 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20d60 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
20d70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20d80 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
20d90 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
20da0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
20db0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20dc0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
20dd0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
20de0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
20df0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
20e00 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
20e10 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
20e20 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
20e30 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
20e40 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
20e50 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20e60 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
20e70 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
20e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
20e90 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
20ea0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
20eb0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
20ec0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
20ed0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
20ee0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
20ef0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
20f00 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
20f10 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
20f20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
20f30 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
20f40 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
20f50 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20f60 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
20f70 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
20f80 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
20f90 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
20fa0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
20fb0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
20fc0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
20fd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
20fe0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
20ff0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
21000 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
21010 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
21020 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
21030 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
21040 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
21050 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
21060 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
21070 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
21080 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
21090 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
210a0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
210b0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
210c0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
210d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
210e0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
210f0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
21100 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
21110 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
21120 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
21130 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
21140 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
21150 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
21160 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
21170 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
21180 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
21190 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
211a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
211b0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
211c0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
211d0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
211e0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
211f0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
21200 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
21210 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
21220 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
21230 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
21240 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
21250 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
21260 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
21270 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
21280 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
21290 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
212a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
212b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
212c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
212d0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
212e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
212f0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
21300 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
21310 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
21320 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
21330 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
21340 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
21350 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
21360 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
21370 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
21380 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
21390 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
213a0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
213b0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
213c0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
213d0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
213e0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
213f0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
21400 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
21410 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
21420 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
21430 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
21440 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
21450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
21460 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
21470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
21480 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
21490 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
214a0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
214b0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
214c0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
214d0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
214e0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
214f0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
21500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
21510 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
21520 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
21530 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
21540 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
21550 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
21560 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
21570 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
21580 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
21590 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
215a0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
215b0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
215c0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
215d0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
215e0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
215f0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
21600 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
21610 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
21620 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
21630 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
21640 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
21650 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
21660 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
21670 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
21680 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
21690 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
216a0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
216b0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
216c0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
216d0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
216e0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
216f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
21700 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
21710 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
21720 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
21730 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
21740 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
21750 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
21760 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
21770 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
21780 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
21790 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
217a0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
217b0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
217c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
217d0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
217e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
217f0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
21800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21810 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
21820 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
21830 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
21840 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
21850 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
21860 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
21870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21880 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
21890 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
218a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
218b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
218c0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
218d0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
218e0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
218f0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
21900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21910 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
21920 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
21930 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
21940 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
21950 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
21960 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
21970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
21980 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
21990 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
219a0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
219b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
219c0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
219d0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
219e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
219f0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
21a00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21a10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
21a20 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
21a30 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
21a40 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
21a50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
21a60 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
21a70 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
21a80 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
21a90 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
21aa0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
21ab0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21ac0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
21ad0 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
21ae0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
21af0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
21b00 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
21b10 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
21b20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
21b30 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
21b40 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
21b50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
21b60 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
21b70 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
21b80 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
21b90 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
21ba0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
21bb0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
21bc0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
21bd0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
21be0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
21bf0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
21c00 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
21c10 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
21c20 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
21c30 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
21c40 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
21c50 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
21c60 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
21c70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
21c80 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
21c90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
21ca0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
21cb0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21cc0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
21cd0 74 73 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20  ts:.** [H13803] 
21ce0 5b 48 31 33 38 30 36 5d 20 5b 48 31 33 38 30 39  [H13806] [H13809
21cf0 5d 20 5b 48 31 33 38 31 32 5d 20 5b 48 31 33 38  ] [H13812] [H138
21d00 31 35 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48 31  15] [H13818] [H1
21d10 33 38 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a  3821] [H13824].*
21d20 2a 20 5b 48 31 33 38 32 37 5d 20 5b 48 31 33 38  * [H13827] [H138
21d30 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  30].*/.const voi
21d40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21d50 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
21d60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21d70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
21d80 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
21d90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21da0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
21db0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
21dc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21dd0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
21de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
21df0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
21e00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
21e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
21e20 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
21e30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21e40 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
21e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
21e60 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
21e70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
21e80 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
21e90 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21ea0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
21eb0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
21ec0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21ee0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21ef0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
21f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21f10 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
21f20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
21f30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
21f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
21f50 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
21f60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
21f70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
21f80 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
21f90 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
21fa0 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33  t {H13300} <S703
21fb0 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
21fc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
21fd0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
21fe0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
21ff0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
22000 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
22010 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
22020 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
22030 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
22040 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
22050 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
22060 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
22070 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  d. If execution 
22080 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
22090 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
220a0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
220b0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
220c0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
220d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
220e0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
220f0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
22100 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
22110 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
22120 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22130 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
22140 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
22150 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
22160 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
22170 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
22180 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
22190 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
221a0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
221b0 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
221c0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
221d0 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63  terrupt]..** Inc
221e0 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
221f0 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
22200 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
22210 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
22220 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
22230 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
22240 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
22250 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
22260 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
22270 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
22280 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
22290 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 31 33 30   [H11302] [H1130
222a0 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  4].*/.int sqlite
222b0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
222c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
222d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
222e0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
222f0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
22300 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37  ect {H13330} <S7
22310 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
22320 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
22330 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
22340 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
22350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22360 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
22370 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
22380 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
22390 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
223a0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
223b0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
223c0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
223d0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
223e0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
223f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
22400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
22410 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
22420 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
22430 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
22440 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
22450 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
22460 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  gs..**.** {H1133
22470 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
22480 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
22490 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
224a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
224b0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
224c0 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
224d0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
224e0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
224f0 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
22500 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
22510 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
22520 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
22530 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
22540 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
22550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
22560 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
22570 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DONE],.**       
22580 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65     or if [sqlite
22590 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
225a0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
225b0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
225c0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
225d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
225e0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
225f0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
22600 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73  1336} If the mos
22610 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
22620 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
22630 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
22640 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22650 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
22660 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
22670 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
22680 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
22690 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
226a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
226b0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
226c0 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {H11338} The [s
226d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
226e0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
226f0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
22700 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
22710 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
22720 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
22730 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
22740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22750 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
22760 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
22770 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22790 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
227a0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
227b0 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32  s {H16100} <S202
227c0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
227d0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
227e0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
227f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
22800 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
22820 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
22830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
22850 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
22860 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
22870 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
22880 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
22890 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
228a0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
228b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
228c0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
228d0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
228e0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
228f0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
22900 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
22910 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
22920 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
22930 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
22940 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
22950 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
22960 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
22970 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
22980 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
22990 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
229a0 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
229b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
229c0 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
229d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
229e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
229f0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
22a00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
22a10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22a20 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
22a30 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
22a40 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
22a50 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
22a60 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
22a70 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
22a80 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
22a90 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
22aa0 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
22ab0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
22ac0 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
22ad0 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
22ae0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
22af0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
22b00 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
22b10 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
22b20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
22b30 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
22b40 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
22b50 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
22b60 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
22b70 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
22b80 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
22b90 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
22ba0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
22bb0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
22bc0 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
22bd0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
22be0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
22bf0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
22c00 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
22c10 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
22c20 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
22c30 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
22c40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
22c50 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
22c60 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
22c70 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
22c80 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
22c90 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
22ca0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
22cb0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
22cc0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
22cd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
22ce0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
22cf0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
22d00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
22d10 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
22d20 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
22d30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
22d40 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
22d50 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
22d60 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
22d70 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
22d80 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
22d90 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
22da0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
22db0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
22dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
22dd0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
22de0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
22df0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
22e00 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
22e10 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
22e20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
22e30 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
22e40 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
22e50 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
22e60 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
22e70 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
22e80 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
22e90 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
22ea0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
22eb0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
22ec0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
22ed0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
22ee0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
22ef0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
22f00 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
22f10 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
22f20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
22f30 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
22f40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
22f50 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
22f60 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
22f70 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
22f80 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
22f90 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
22fa0 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
22fb0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
22fc0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
22fd0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
22fe0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
22ff0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
23000 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
23010 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
23020 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
23030 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
23040 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
23050 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
23060 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
23070 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
23080 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
23090 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
230a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
230b0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
230c0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
230d0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
230e0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
230f0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
23100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
23110 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
23120 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
23130 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
23140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23150 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a  user_data()]..**
23160 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
23170 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
23180 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
23190 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
231a0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
231b0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
231c0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
231d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
231e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
231f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
23200 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
23210 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
23220 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
23230 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
23240 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20   callback only, 
23250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68  NULL pointers sh
23260 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61  ould be passed a
23270 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
23280 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
23290 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61  ters. An aggrega
232a0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
232b0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
232c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
232d0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
232e0 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c  l and NULL shoul
232f0 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  d be passed for 
23300 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65  xFunc. To delete
23310 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
23320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
23330 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
23340 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72  NULL for all thr
23350 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ee function call
23360 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  backs..**.** It 
23370 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
23380 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
23390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
233a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
233b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
233c0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
233d0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
233e0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
233f0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
23400 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
23410 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
23420 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
23430 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
23440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
23450 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
23460 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
23470 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
23480 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
23490 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70    A function imp
234a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
234b0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
234c0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
234d0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
234e0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
234f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
23500 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
23510 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66  ative nArg.  A f
23520 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
23530 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
23540 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
23550 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
23560 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
23570 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
23580 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
23590 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
235a0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
235b0 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e    .** A function
235c0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
235d0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
235e0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
235f0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
23600 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
23610 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
23620 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
23630 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
23640 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
23650 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
23660 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75  *.** Built-in fu
23670 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
23680 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
23690 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
236a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
236b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70  ** The first app
236c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
236d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
236e0 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72   given name over
236f0 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69  rides all.** bui
23700 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
23710 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  in the same [dat
23720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23730 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  ] with the same 
23740 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75  name..** Subsequ
23750 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ent application-
23760 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
23770 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61  s of the same na
23780 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65  me only override
23790 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69   .** prior appli
237a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
237b0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72  unctions that ar
237c0 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68  e an exact match
237d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62   for the.** numb
237e0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
237f0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65   and preferred e
23800 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41  ncoding..**.** A
23810 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
23820 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
23830 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
23840 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
23850 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
23860 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
23870 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
23880 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
23890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
238a0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
238b0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
238c0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
238d0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
238e0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
238f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
23900 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d  nts:.** [H16103]
23910 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30   [H16106] [H1610
23920 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36  9] [H16112] [H16
23930 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48  118] [H16121] [H
23940 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33  16127].** [H1613
23950 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36  0] [H16133] [H16
23960 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48  136] [H16139] [H
23970 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16142].*/.int sq
23980 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23990 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
239a0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
239b0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
239c0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
239d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
239e0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
239f0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
23a00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
23a10 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
23a20 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
23a30 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
23a40 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
23a50 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
23a60 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
23a70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
23a80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
23a90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
23aa0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
23ab0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
23ac0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
23ad0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
23ae0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
23af0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
23b00 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
23b10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
23b20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
23b30 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
23b40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
23b50 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
23b60 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
23b70 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
23b80 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
23b90 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
23ba0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
23bb0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
23bc0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
23bd0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
23be0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
23bf0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
23c00 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
23c10 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
23c20 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
23c30 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
23c40 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
23c50 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
23c60 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
23c70 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
23c80 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
23c90 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
23ca0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
23cb0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
23cc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
23cd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23ce0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
23cf0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
23d00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23d10 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
23d20 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
23d30 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
23d40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
23d50 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
23d60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23d70 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
23d80 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
23d90 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
23da0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
23db0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
23dc0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
23dd0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
23de0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
23df0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
23e00 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
23e10 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
23e20 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
23e30 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
23e40 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
23e50 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
23e60 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
23e70 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
23e80 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
23e90 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
23ea0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
23eb0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
23ec0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
23ed0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
23ee0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
23ef0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
23f00 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
23f10 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
23f20 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
23f30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
23f40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
23f60 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
23f70 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
23f80 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
23f90 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
23fa0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
23fb0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
23fc0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23fd0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23fe0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
23ff0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
24000 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
24010 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
24020 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
24030 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
24040 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
24050 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
24060 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
24070 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
24080 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
24090 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
240a0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
240b0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
240c0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
240d0 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
240e0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
240f0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
24100 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
24110 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
24120 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
24130 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
24140 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
24150 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
24160 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
24170 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
24180 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
24190 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
241a0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
241b0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
241c0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
241d0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
241e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
241f0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
24200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24210 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
24220 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
24230 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
24240 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
24250 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
24260 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
24270 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
24280 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
24290 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
242a0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
242b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
242c0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
242d0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
242e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
242f0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
24300 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
24310 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
24320 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
24330 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
24340 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
24350 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
24360 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
24370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
24380 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
24390 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
243a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
243b0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
243c0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
243d0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
243e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
243f0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
24400 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
24410 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
24420 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24430 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
24440 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
24450 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
24460 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
24470 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
24480 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
24490 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
244a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
244b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
244c0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
244d0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
244e0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
244f0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
24500 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
24510 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
24520 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
24530 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
24540 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
24550 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
24560 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
24570 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
24580 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
24590 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
245a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
245b0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
245c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
245d0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
245e0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
245f0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
24600 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
24610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24620 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
24630 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
24640 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
24650 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
24660 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
24670 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
24680 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
24690 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
246a0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
246b0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
246c0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
246d0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
246e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
246f0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
24700 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
24710 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
24720 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
24730 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
24740 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
24750 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
24760 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
24770 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
24780 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
24790 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
247a0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
247b0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
247c0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
247d0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
247e0 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
247f0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
24800 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
24810 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
24820 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
24830 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
24840 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
24850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
24860 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
24870 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24880 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
24890 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
248a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
248b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
248c0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
248d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
248e0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
248f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
24900 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
24910 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
24920 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24930 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
24940 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
24950 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
24960 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
24970 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
24980 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
24990 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
249a0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
249b0 73 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b  s:.** [H15103] [
249c0 48 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d  H15106] [H15109]
249d0 20 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31   [H15112] [H1511
249e0 35 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35  5] [H15118] [H15
249f0 31 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a  121] [H15124].**
24a00 20 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33   [H15127] [H1513
24a10 30 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35  0] [H15133] [H15
24a20 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  136].*/.const vo
24a30 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
24a40 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
24a50 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
24a60 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
24a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24a80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
24a90 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
24aa0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
24ab0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
24ac0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24ad0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
24ae0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
24af0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24b00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
24b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
24b20 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
24b30 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
24b40 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
24b50 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
24b60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
24b70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24b80 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
24b90 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
24ba0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24bb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
24bc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24bd0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24be0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24bf0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
24c00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
24c10 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
24c20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
24c30 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
24c40 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
24c50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
24c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
24c70 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
24c80 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
24c90 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30   {H16210} <S2020
24ca0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0>.**.** The imp
24cb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
24cc0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
24cd0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
24ce0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
24cf0 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
24d00 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
24d10 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
24d20 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
24d30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
24d40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
24d50 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
24d60 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74  ed for a.** part
24d70 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
24d80 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
24d90 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
24da0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
24db0 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  that.** memory, 
24dc0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
24dd0 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20  inter to it. On 
24de0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
24df0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
24e00 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
24e10 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
24e20 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
24e30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
24e40 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  dex,.** the same
24e50 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
24e60 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  ned. The impleme
24e70 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61  ntation of the a
24e80 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
24e90 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64  .** the returned
24ea0 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
24eb0 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
24ec0 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  * SQLite automat
24ed0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
24ee0 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65   allocated buffe
24ef0 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  r when the aggre
24f00 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
24f10 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
24f20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24f30 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
24f40 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
24f50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
24f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
24f70 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
24f80 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24f90 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
24fa0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
24fb0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
24fc0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
24fd0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
24fe0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
24ff0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
25000 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
25010 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
25020 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
25030 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
25040 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
25050 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20  ts:.** [H16211] 
25060 5b 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35  [H16213] [H16215
25070 5d 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f  ] [H16217].*/.vo
25080 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
25090 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
250a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
250b0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
250c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
250d0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
250e0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
250f0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
25100 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
25110 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
25120 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
25130 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
25140 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
25150 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
25160 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
25170 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
25180 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25190 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
251a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
251b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
251c0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
251d0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
251e0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
251f0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
25200 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
25210 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
25220 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
25230 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
25240 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
25250 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
25260 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
25270 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
25280 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
25290 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a  ts:.** [H16243].
252a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
252b0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
252c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
252d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
252e0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
252f0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
25300 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30   {H16250} <S6060
25310 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20200>.**.**
25320 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
25330 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
25340 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25350 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
25360 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
25370 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25380 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
25390 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
253a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
253b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
253c0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
253d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
253e0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
253f0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
25400 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
25410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
25420 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
25430 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
25440 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d  nts:.** [H16253]
25450 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
25460 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
25470 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
25480 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
25490 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
254a0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
254b0 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30  ta {H16270} <S20
254c0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  200>.**.** The f
254d0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
254e0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
254f0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
25500 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
25510 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
25520 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
25530 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
25540 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
25550 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
25560 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
25570 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
25580 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
25590 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
255a0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
255b0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
255c0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
255d0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
255e0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
255f0 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
25600 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
25610 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
25620 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
25630 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
25640 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
25650 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
25660 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
25670 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
25680 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
25690 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
256a0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
256b0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
256c0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
256d0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
256e0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
256f0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
25700 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
25710 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
25720 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
25730 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
25740 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
25750 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
25760 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
25770 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
25780 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
25790 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
257a0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
257b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
257c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
257d0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
257e0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
257f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25800 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
25810 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
25820 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
25830 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25840 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25850 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
25860 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
25870 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
25880 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
25890 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
258a0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
258b0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
258c0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
258d0 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
258e0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
258f0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
25900 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
25910 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
25920 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
25930 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25940 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
25950 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
25960 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
25970 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
25980 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
25990 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
259a0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
259b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
259c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
259d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
259e0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
259f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
25a00 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
25a10 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
25a20 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
25a30 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
25a40 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
25a50 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
25a60 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
25a70 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
25a80 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
25a90 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
25aa0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
25ab0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
25ac0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
25ad0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
25ae0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
25af0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
25b00 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
25b10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
25b20 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
25b30 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
25b40 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
25b50 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
25b60 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
25b70 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
25b80 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
25b90 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
25ba0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
25bb0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
25bc0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
25bd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
25be0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
25bf0 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
25c00 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
25c10 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
25c20 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
25c30 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
25c40 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
25c50 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
25c60 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
25c70 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
25c80 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
25c90 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
25ca0 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
25cb0 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
25cc0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
25cd0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
25ce0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
25cf0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
25d00 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
25d10 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
25d20 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
25d30 31 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20  16272] [H16274] 
25d40 5b 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37  [H16276] [H16277
25d50 5d 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32  ] [H16278] [H162
25d60 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  79].*/.void *sql
25d70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
25d80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25d90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
25da0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25db0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
25dc0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
25dd0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
25de0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
25df0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
25e00 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
25e10 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
25e20 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
25e30 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
25e40 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
25e50 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
25e60 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
25e70 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
25e80 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
25e90 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
25ea0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
25eb0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
25ec0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
25ed0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
25ee0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
25ef0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
25f00 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
25f10 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
25f20 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
25f30 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
25f40 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
25f50 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
25f60 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
25f70 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
25f80 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
25f90 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
25fa0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
25fb0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
25fc0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
25fd0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
25fe0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
25ff0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
26000 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
26010 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
26020 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
26030 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
26040 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
26050 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
26060 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
26070 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
26080 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
26090 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
260a0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
260b0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
260c0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
260d0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
260e0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
260f0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
26100 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
26110 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
26120 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
26130 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
26140 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
26150 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
26160 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
26170 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
26180 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
26190 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
261a0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
261b0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
261c0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
261d0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
261e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
261f0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
26200 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26210 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
26220 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26230 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
26240 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
26250 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
26260 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
26270 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
26280 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
26290 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
262a0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
262b0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
262c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
262d0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
262e0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
262f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
26300 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
26310 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
26320 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
26330 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
26340 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
26350 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
26360 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26370 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26380 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
26390 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
263a0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
263b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
263c0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
263d0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
263e0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
263f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
26400 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26410 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
26420 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
26430 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
26440 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
26450 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26460 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
26470 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
26480 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
26490 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
264a0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
264b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
264c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
264d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
264e0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
264f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26500 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
26510 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
26520 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26530 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
26540 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
26550 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
26560 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
26570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26590 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
265a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
265b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
265c0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
265d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
265e0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
265f0 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
26600 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
26610 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
26620 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
26630 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
26640 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
26650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26660 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
26670 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
26680 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
26690 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
266a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
266b0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
266c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
266d0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
266e0 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
266f0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
26700 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
26710 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
26720 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
26730 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
26740 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
26750 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
26770 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
26780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26790 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
267a0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
267b0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
267c0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
267d0 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
267e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
267f0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
26800 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
26810 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
26820 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
26830 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
26840 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
26850 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
26860 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
26870 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
26880 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
26890 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
268a0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
268b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
268c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
268d0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
268e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
268f0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
26900 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
26910 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
26920 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
26930 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
26940 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
26950 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
26960 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
26970 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
26980 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
26990 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
269a0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
269b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
269c0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
269d0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
269e0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
269f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
26a00 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
26a10 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
26a20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
26a30 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
26a40 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
26a50 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
26a60 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
26a70 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
26a80 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
26a90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26aa0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
26ab0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
26ac0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
26ad0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26ae0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
26af0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
26b00 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
26b10 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
26b20 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
26b30 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
26b40 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
26b50 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
26b60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26b70 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
26b80 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
26b90 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
26ba0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
26bb0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
26bc0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
26bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26be0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
26bf0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26c00 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
26c10 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
26c20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26c30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
26c40 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
26c50 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
26c60 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
26c70 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
26c80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26c90 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
26ca0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
26cb0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
26cc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26cd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26ce0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
26cf0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26d00 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
26d10 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
26d20 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
26d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
26d40 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
26d50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
26d60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
26d70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26d80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26d90 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
26da0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26db0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
26dc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
26dd0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
26de0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
26df0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
26e00 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
26e10 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
26e20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
26e30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
26e40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26e50 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
26e60 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
26e70 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
26e80 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
26e90 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
26ea0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
26eb0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
26ec0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
26ed0 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
26ee0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
26ef0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
26f00 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
26f10 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
26f20 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
26f30 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
26f40 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26f50 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
26f60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
26f70 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
26f80 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
26f90 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
26fa0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
26fb0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
26fc0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
26fd0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
26fe0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
26ff0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
27000 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
27010 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
27020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27030 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
27040 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
27050 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
27060 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
27070 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
27080 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
27090 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
270a0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
270b0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
270c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
270d0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
270e0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
270f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
27100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27110 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
27120 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
27130 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
27140 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
27150 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
27160 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
27170 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
27180 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
27190 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
271a0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
271b0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
271c0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
271d0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
271e0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
271f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
27200 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
27210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27220 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
27230 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
27240 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
27250 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
27260 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
27270 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
27280 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
27290 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
272a0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
272b0 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
272c0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
272d0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
272e0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
272f0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
27300 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
27310 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27320 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
27330 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
27340 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
27350 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
27360 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
27370 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
27380 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
27390 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
273a0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
273b0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
273c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
273d0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
273e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
273f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
27400 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
27410 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
27420 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
27430 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27440 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
27450 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
27460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27470 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
27480 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
27490 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
274a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
274b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
274c0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
274d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
274e0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
274f0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
27500 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
27510 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
27520 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
27530 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
27540 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
27550 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
27560 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
27570 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
27580 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27590 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
275a0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
275b0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
275c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
275d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
275e0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
275f0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
27600 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27610 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
27620 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
27630 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
27640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27650 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
27660 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
27670 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
27680 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
27690 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
276a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
276b0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
276c0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
276d0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
276e0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
276f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
27700 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
27710 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d  nts:.** [H16403]
27720 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30   [H16406] [H1640
27730 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36  9] [H16412] [H16
27740 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48  415] [H16418] [H
27750 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a  16421] [H16424].
27760 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36  ** [H16427] [H16
27770 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48  430] [H16433] [H
27780 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20  16436] [H16439] 
27790 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35  [H16442] [H16445
277a0 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48  ] [H16448].** [H
277b0 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20  16451] [H16454] 
277c0 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30  [H16457] [H16460
277d0 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f  ] [H16463].*/.vo
277e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
277f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
27800 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27810 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27820 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27840 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
27850 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
27860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27870 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
27880 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27890 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
278a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
278b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
278c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
278d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
278e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
278f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
27900 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
27910 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
27920 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
27930 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
27940 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
27950 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27960 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
27970 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
27980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27990 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
279a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
279b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
279c0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
279d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
279e0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
279f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27a00 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
27a10 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
27a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27a30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27a40 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
27a50 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27a60 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27a70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27a80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27a90 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
27aa0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27ab0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27ac0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27ad0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
27ae0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
27af0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
27b00 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
27b10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
27b20 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
27b30 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
27b40 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
27b50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
27b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
27b70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
27b80 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
27b90 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
27ba0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
27bb0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
27bc0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
27bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
27be0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
27bf0 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
27c00 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
27c10 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
27c20 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
27c30 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
27c40 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
27c50 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
27c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
27c70 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
27c80 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
27c90 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
27ca0 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
27cb0 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
27cc0 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
27cd0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
27ce0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27cf0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
27d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27d10 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
27d20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
27d30 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
27d40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27d50 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
27d60 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
27d70 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
27d80 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
27d90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
27da0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
27db0 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
27dc0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
27dd0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
27de0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
27df0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
27e00 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
27e10 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
27e20 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
27e30 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
27e40 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
27e50 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
27e60 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
27e70 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
27e80 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
27e90 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
27ea0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
27eb0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
27ec0 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
27ed0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
27ee0 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
27ef0 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
27f00 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
27f10 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
27f20 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
27f30 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27f40 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
27f50 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
27f60 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
27f70 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
27f80 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
27f90 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
27fa0 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
27fb0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
27fc0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
27fd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
27fe0 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
27ff0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
28000 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
28010 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
28020 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
28030 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
28040 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
28050 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
28060 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
28070 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
28080 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
28090 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
280a0 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
280b0 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
280c0 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
280d0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
280e0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
280f0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
28100 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
28110 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
28120 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
28130 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
28140 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28150 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
28160 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28170 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
28180 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
28190 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
281a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
281b0 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
281c0 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
281d0 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
281e0 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
281f0 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
28200 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
28210 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
28220 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
28230 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28240 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
28250 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
28260 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
28270 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
28280 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
28290 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
282a0 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
282b0 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
282c0 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
282d0 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
282e0 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
282f0 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
28300 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
28310 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
28320 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
28330 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
28340 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
28350 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
28360 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
28370 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28380 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
28390 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
283a0 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
283b0 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
283c0 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
283d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
283e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
283f0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
28400 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
28410 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
28420 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
28430 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
28440 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
28450 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
28460 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28470 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
28480 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
28490 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
284a0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
284b0 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
284c0 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
284d0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
284e0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
284f0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
28500 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
28510 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
28520 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
28530 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28540 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
28550 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
28560 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
28570 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
28580 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
28590 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36  ements:.** [H166
285a0 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31  03] [H16604] [H1
285b0 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b  6606] [H16609] [
285c0 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d  H16612] [H16615]
285d0 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32   [H16618] [H1662
285e0 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b  1].** [H16624] [
285f0 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d  H16627] [H16630]
28600 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28610 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28620 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
28630 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
28640 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
28650 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
28660 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
28670 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28680 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28690 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
286a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
286b0 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
286c0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
286d0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
286e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
286f0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
28700 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
28710 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
28720 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
28730 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
28740 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
28750 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28760 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
28770 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
28780 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
28790 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
287a0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
287b0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
287c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
287d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
287e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
287f0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
28800 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
28810 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
28820 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
28830 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
28840 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
28850 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
28860 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
28870 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
28880 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
28890 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
288a0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
288b0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
288c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
288d0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
288e0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
288f0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
28900 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
28910 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
28920 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
28930 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
28940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
28950 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
28960 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
28970 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
28980 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
28990 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
289a0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
289b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
289c0 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
289d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
289e0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
289f0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
28a00 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
28a10 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
28a20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
28a30 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
28a40 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
28a50 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
28a60 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
28a70 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
28a80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
28a90 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
28aa0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
28ab0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
28ac0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28ad0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
28ae0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28af0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
28b00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28b10 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
28b20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28b30 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28b40 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
28b50 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
28b60 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
28b70 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
28b80 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
28b90 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
28ba0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
28bb0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
28bc0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
28bd0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
28be0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
28bf0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
28c00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
28c10 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
28c20 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
28c30 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
28c40 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
28c50 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
28c60 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
28c70 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
28c80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
28c90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28ca0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
28cb0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
28cc0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
28cd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28ce0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
28cf0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
28d00 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37  * [H16702] [H167
28d10 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a  04] [H16706].*/.
28d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
28d30 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
28d40 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
28d50 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
28d60 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
28d70 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
28d80 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
28d90 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
28da0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
28db0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
28dc0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
28dd0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
28de0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
28df0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
28e00 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
28e10 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
28e20 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
28e30 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
28e40 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
28e50 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
28e60 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
28e70 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
28e80 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
28e90 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
28ea0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
28eb0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
28ec0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28ed0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
28ee0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
28ef0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
28f00 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
28f10 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28f20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
28f30 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
28f40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
28f50 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
28f60 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
28f70 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
28f80 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
28f90 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
28fa0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
28fb0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
28fc0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
28fd0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
28fe0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
28ff0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
29000 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
29010 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
29020 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
29030 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
29040 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
29050 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
29060 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29080 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
29090 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
290a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
290b0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
290c0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
290d0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
290e0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
290f0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
29100 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
29110 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
29120 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
29130 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
29140 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
29150 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
29160 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
29170 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
29180 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
29190 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
291a0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
291b0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
291c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
291d0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
291e0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
291f0 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
29200 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
29210 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
29220 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
29230 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
29240 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
29250 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
29260 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
29270 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
29280 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
29290 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
292a0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
292b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
292c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
292d0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
292e0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
292f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
29300 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
29310 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
29320 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29330 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31  ts: [H10533] [H1
29340 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  0536].*/.int sql
29350 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
29360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29370 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
29380 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
29390 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31  porary Files {H1
293a0 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0310} <S20000>.*
293b0 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
293c0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
293d0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
293e0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
293f0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
29400 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
29410 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
29420 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
29430 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
29440 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
29450 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
29460 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
29470 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
29480 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
29490 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
294a0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
294b0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
294c0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
294d0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
294e0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
294f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
29500 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
29510 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
29520 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
29530 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
29540 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
29550 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
29560 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
29570 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
29580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
29590 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
295a0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
295b0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
295c0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
295d0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
295e0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
295f0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
29600 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
29610 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
29620 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
29630 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
29640 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
29650 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
29660 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
29670 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
29680 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
29690 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f  **.** The [temp_
296a0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
296b0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
296c0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
296d0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
296e0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
296f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
29700 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
29710 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  c].  Furthermore
29720 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
29730 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
29740 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
29750 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
29760 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
29770 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
29780 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
29790 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
297a0 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
297b0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
297c0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
297d0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
297e0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
297f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
29800 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
29810 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
29820 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
29830 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
29840 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
29850 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
29860 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
29870 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
29880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
29890 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
298a0 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
298b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
298c0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
298d0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
298e0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
298f0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
29900 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
29910 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
29920 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
29930 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
29940 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
29950 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
29960 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
29970 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
29980 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
29990 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
299a0 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
299b0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
299c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
299d0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
299e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
299f0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29a00 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
29a10 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
29a20 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
29a30 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
29a40 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
29a50 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
29a60 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
29a70 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
29a80 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
29a90 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
29aa0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
29ab0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
29ac0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
29ad0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
29ae0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
29af0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
29b00 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
29b10 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
29b20 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
29b30 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
29b40 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
29b50 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
29b60 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
29b70 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
29b80 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
29b90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
29ba0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
29bb0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
29bc0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
29bd0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
29be0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
29bf0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
29c00 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
29c10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
29c20 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
29c30 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
29c40 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
29c50 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
29c60 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
29c70 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
29c80 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
29c90 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
29ca0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
29cb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
29cc0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
29cd0 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b  2931] [H12932] [
29ce0 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d  H12933] [H12934]
29cf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29d00 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
29d10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
29d20 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
29d30 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
29d40 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
29d50 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
29d60 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  120} <S60600>.**
29d70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29d80 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
29d90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29db0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
29dc0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
29dd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29de0 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64  belongs.  The [d
29df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29e00 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
29e10 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
29e20 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
29e30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29e40 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20  ction] that was 
29e50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
29e60 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
29e70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29e80 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
29e90 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
29ea0 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
29eb0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
29ec0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
29ed0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65   place..**.** Re
29ee0 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
29ef0 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  123].*/.sqlite3 
29f00 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
29f10 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
29f20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29f30 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
29f40 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
29f50 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53  ment {H13140} <S
29f60 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60600>.**.** Thi
29f70 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
29f80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29f90 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
29fa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
29fb0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
29fc0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
29fd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29fe0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
29ff0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
2a000 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
2a010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2a020 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2a030 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
2a040 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
2a050 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
2a060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a070 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70  on pDb.  If no p
2a080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a090 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2a0a0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2a0b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2a0c0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2a0d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2a0e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a0f0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2a100 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a110 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2a120 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2a130 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2a140 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2a150 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2a160 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2a170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2a180 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2a190 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31  : [H13143] [H131
2a1a0 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31  46] [H13149] [H1
2a1b0 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3152].*/.sqlite3
2a1c0 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2a1d0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2a1e0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2a1f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a210 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2a220 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2a230 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
2a240 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
2a250 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
2a260 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
2a270 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2a280 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2a290 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2a2a0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2a2b0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
2a2c0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
2a2d0 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  d]..** Any callb
2a2e0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2a2f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2a300 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2a310 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2a320 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2a330 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2a340 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
2a350 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2a360 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2a370 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2a380 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2a390 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2a3a0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2a3b0 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2a3c0 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2a3d0 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  ]..** Any callba
2a3e0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2a3f0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2a400 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2a410 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2a420 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2a430 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2a440 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72  dden..** The pAr
2a450 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2a460 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2a470 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2a480 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
2a490 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
2a4a0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
2a4b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
2a4c0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
2a4d0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2a4e0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
2a4f0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
2a500 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
2a510 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2a520 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
2a530 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2a540 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
2a550 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
2a560 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2a570 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2a580 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2a590 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2a5a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2a5b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a5c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2a5d0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
2a5e0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2a5f0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2a600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2a610 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2a620 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2a630 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2a640 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2a650 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2a660 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
2a670 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
2a680 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
2a690 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
2a6a0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2a6b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a6c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2a6d0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2a6e0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2a6f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2a700 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2a710 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2a720 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2a730 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
2a740 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2a750 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2a760 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
2a770 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2a780 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
2a790 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
2a7a0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
2a7b0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
2a7c0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
2a7d0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 49 66  ue normally.  If
2a7e0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2a7f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2a800 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2a810 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2a820 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2a830 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72  LBACK]..** The r
2a840 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2a850 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2a860 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2a870 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2a880 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2a890 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2a8a0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2a8b0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2a8c0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2a8d0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
2a8e0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
2a8f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
2a900 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
2a910 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2a920 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
2a930 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
2a940 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
2a950 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
2a960 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
2a970 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
2a980 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
2a990 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
2a9a0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2a9b0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2a9c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2a9d0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2a9e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2a9f0 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
2aa00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2aa10 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
2aa20 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2aa30 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2aa40 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2aa50 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
2aa60 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
2aa70 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
2aa80 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
2aa90 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
2aaa0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
2aab0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2aac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2aad0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2aae0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  face..**.** Requ
2aaf0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
2ab00 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b  2951] [H12952] [
2ab10 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d  H12953] [H12954]
2ab20 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31   [H12955].** [H1
2ab30 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b  2961] [H12962] [
2ab40 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d  H12963] [H12964]
2ab50 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ab60 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2ab70 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2ab80 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2ab90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2aba0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2abb0 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2abc0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2abd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2abe0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2abf0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2ac00 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34  s {H12970} <S604
2ac10 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2ac20 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2ac30 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2ac40 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2ac50 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2ac60 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2ac70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2ac80 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2ac90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2aca0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2acb0 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2acc0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2acd0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2ace0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2acf0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2ad00 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2ad10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2ad20 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2ad30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2ad40 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2ad50 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2ad60 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2ad70 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2ad80 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2ad90 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2ada0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2adb0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68  r deleted..** Th
2adc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2add0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2ade0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2adf0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2ae00 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
2ae10 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
2ae20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
2ae30 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2ae40 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2ae50 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2ae60 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
2ae70 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
2ae80 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2ae90 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2aea0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2aeb0 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
2aec0 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
2aed0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2aee0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2aef0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2af00 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2af10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2af20 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2af30 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2af40 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
2af50 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2af60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2af70 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
2af80 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
2af90 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2afa0 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2afb0 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2afc0 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2afd0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2afe0 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2aff0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2b000 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2b010 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2b020 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2b030 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2b040 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a  te_sequence)..**
2b050 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 72 65  .** In the curre
2b060 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2b070 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2b080 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2b090 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2b0a0 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2b0b0 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2b0c0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2b0d0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2b0e0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2b0f0 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 65 20  se.  Nor is the 
2b100 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2b110 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2b120 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2b130 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2b140 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2b150 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2b160 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2b170 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2b180 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2b190 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2b1a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2b1b0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2b1c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b1d0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2b1e0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2b1f0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2b200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b210 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2b220 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2b230 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2b240 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2b250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b260 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2b270 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2b280 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2b290 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b2a0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2b2b0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2b2c0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2b2d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2b2e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b2f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2b300 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2b310 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2b320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2b330 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2b340 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2b350 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2b360 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2b370 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
2b380 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2b390 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
2b3a0 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
2b3b0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
2b3c0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
2b3d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2b3e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
2b3f0 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
2b400 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2b410 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
2b420 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  rfaces..**.** Re
2b430 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
2b440 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33 5d  H12971] [H12973]
2b450 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39 37   [H12975] [H1297
2b460 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31 32  7] [H12979] [H12
2b470 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48  981] [H12983] [H
2b480 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12986].*/.void *
2b490 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2b4a0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
2b4b0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2b4c0 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
2b4d0 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
2b4e0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2b4f0 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
2b500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2b510 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2b520 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2b530 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30  he {H10330} <S30
2b540 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  900>.** KEYWORDS
2b550 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
2b560 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   {shared cache m
2b570 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ode}.**.** This 
2b580 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2b590 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2b5a0 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2b5b0 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2b5c0 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2b5d0 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2b5e0 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
2b5f0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
2b600 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
2b610 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
2b620 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
2b630 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2b640 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
2b650 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
2b660 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
2b670 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68  alse..**.** Cach
2b680 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
2b690 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
2b6a0 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
2b6b0 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
2b6c0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
2b6d0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
2b6e0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
2b6f0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
2b700 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
2b710 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2b720 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
2b730 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
2b740 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
2b750 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
2b760 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
2b770 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
2b780 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
2b790 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
2b7a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2b7b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b7c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
2b7d0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
2b7e0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
2b7f0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
2b800 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
2b810 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
2b820 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
2b830 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
2b840 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
2b850 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
2b860 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
2b870 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
2b880 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72  ache.  When shar
2b890 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
2b8a0 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
2b8b0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2b8c0 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
2b8d0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
2b8e0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
2b8f0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
2b900 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
2b910 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2b920 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2b930 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
2b940 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2b950 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
2b960 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
2b970 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2b980 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
2b990 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
2b9a0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
2b9b0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
2b9c0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
2b9d0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
2b9e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2b9f0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
2ba00 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
2ba10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
2ba20 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
2ba30 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
2ba40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c  ly..**.** See Al
2ba50 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61  so:  [SQLite Sha
2ba60 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a  red-Cache Mode].
2ba70 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2ba80 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48 31  ts: [H10331] [H1
2ba90 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b  0336] [H10337] [
2baa0 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H10339].*/.int s
2bab0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2bac0 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2bad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bae0 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2baf0 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48  e Heap Memory {H
2bb00 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a  17340} <S30220>.
2bb10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2bb20 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2bb30 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2bb40 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20  empts to free N 
2bb50 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70  bytes.** of heap
2bb60 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
2bb70 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
2bb80 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ntial memory all
2bb90 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64  ocations.** held
2bba0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2bbb0 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20   library. {END} 
2bbc0 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
2bbd0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
2bbe0 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
2bbf0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
2bc00 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
2bc10 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
2bc20 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  mory..** sqlite3
2bc30 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2bc40 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
2bc50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
2bc60 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
2bc70 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
2bc80 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
2bc90 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
2bca0 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  uested..**.** Re
2bcb0 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37  quirements: [H17
2bcc0 33 34 31 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f  341] [H17342].*/
2bcd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2bce0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2bcf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bd00 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2bd10 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b  t On Heap Size {
2bd20 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e  H17350} <S30220>
2bd30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2bd40 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
2bd50 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70  it() interface p
2bd60 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
2bd70 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61  imit.** on the a
2bd80 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
2bd90 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
2bda0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
2bdb0 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69  Lite..** If an i
2bdc0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2bdd0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2bde0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2bdf0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2be00 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2be10 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2be20 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2be30 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2be40 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2be50 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2be60 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2be70 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2be80 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69  *.** The limit i
2be90 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c  s called "soft",
2bea0 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2beb0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2bec0 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2bed0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2bee0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2bef0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2bf00 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2bf10 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2bf20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2bf30 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2bf40 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2bf50 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  oceeds..**.** A 
2bf60 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
2bf70 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
2bf80 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
2bf90 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
2bfa0 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
2bfb0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2bfc0 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
2bfd0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
2bfe0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
2bff0 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ed..** The defau
2c000 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2c010 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2c020 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
2c030 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
2c040 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
2c050 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
2c060 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20  p limit..** But 
2c070 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  if the soft heap
2c080 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65   limit cannot be
2c090 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74   honored, execut
2c0a0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
2c0b0 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
2c0c0 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
2c0d0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
2c0e0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a   the limit is.**
2c0f0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
2c100 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
2c110 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
2c120 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
2c130 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2c140 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
2c150 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
2c160 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2c170 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
2c180 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
2c190 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2c1a0 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
2c1b0 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
2c1c0 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
2c1d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2c1e0 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
2c1f0 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
2c200 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
2c210 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
2c220 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
2c230 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2c240 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
2c250 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
2c260 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2c270 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
2c280 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
2c290 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
2c2a0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
2c2b0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
2c2c0 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
2c2d0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
2c2e0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  reads..**.** Req
2c2f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
2c300 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20  16351] [H16352] 
2c310 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34  [H16353] [H16354
2c320 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33  ] [H16355] [H163
2c330 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  58].*/.void sqli
2c340 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2c350 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
2c360 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
2c370 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
2c380 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
2c390 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c  Table {H12850} <
2c3a0 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60300>.**.** Th
2c3b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2c3c0 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75  ns metadata abou
2c3d0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
2c3e0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
2c3f0 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61  c.** database ta
2c400 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
2c410 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61  sing the [databa
2c420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
2c430 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20  andle.** passed 
2c440 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
2c450 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2c460 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
2c470 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
2c480 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
2c490 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2c4a0 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
2c4b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
2c4c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2c4d0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
2c4e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2c4f0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
2c500 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f  "main", "temp" o
2c510 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2c520 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2c530 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2c540 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2c550 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  L. If it is NULL
2c560 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2c570 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2c580 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2c590 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2c5a0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2c5b0 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2c5c0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2c5d0 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2c5e0 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2c5f0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2c600 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
2c610 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c620 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2c630 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
2c640 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
2c650 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
2c660 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
2c670 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
2c680 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
2c690 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
2c6a0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
2c6b0 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2c6c0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2c6d0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2c6e0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2c6f0 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2c700 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2c710 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2c720 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
2c730 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  e arguments may 
2c740 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77  be.** NULL, in w
2c750 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
2c760 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
2c770 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20  ent of metadata 
2c780 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  is omitted..**.*
2c790 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2c7a0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2c7b0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2c7c0 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
2c7d0 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
2c7e0 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
2c7f0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2c800 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
2c810 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
2c820 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
2c830 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
2c840 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
2c850 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
2c860 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
2c870 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
2c880 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2c890 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2c8a0 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
2c8b0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
2c8c0 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
2c8d0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2c8e0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2c8f0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
2c900 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
2c910 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
2c920 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2c930 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2c940 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
2c950 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
2c960 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2c970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
2c980 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
2c990 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
2c9a0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2c9b0 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
2c9c0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
2c9d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c9e0 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
2c9f0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
2ca00 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
2ca10 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
2ca20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
2ca30 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
2ca40 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
2ca50 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
2ca60 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2ca70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
2ca80 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
2ca90 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
2caa0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
2cab0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
2cac0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
2cad0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
2cae0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2caf0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
2cb00 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
2cb10 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
2cb20 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
2cb30 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
2cb40 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
2cb50 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
2cb60 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49  red [INTEGER PRI
2cb70 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2cb80 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
2cb90 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
2cba0 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f  are set as follo
2cbb0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
2cbc0 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
2cbd0 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
2cbe0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
2cbf0 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
2cc00 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
2cc10 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
2cc20 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
2cc30 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
2cc40 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  0.** </pre>.**.*
2cc50 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
2cc60 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2cc70 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2cc80 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2cc90 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2cca0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2ccb0 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2ccc0 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2ccd0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2cce0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2ccf0 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2cd00 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2cd10 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2cd20 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2cd30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2cd40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2cd50 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2cd60 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2cd70 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ())..**.** This 
2cd80 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
2cd90 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2cda0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2cdb0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2cdc0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2cdd0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2cde0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2cdf0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  bol defined..*/.
2ce00 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
2ce10 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
2ce20 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
2ce30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ce40 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
2ce50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ce60 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
2ce70 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ce80 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
2ce90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2cea0 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
2ceb0 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
2cec0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ced0 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
2cee0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
2cef0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2cf00 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
2cf10 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
2cf20 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
2cf30 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2cf40 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
2cf50 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
2cf60 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
2cf70 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
2cf80 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
2cf90 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2cfa0 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
2cfb0 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73  onstraint exists
2cfc0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d   */.  int *pPrim
2cfd0 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20  aryKey,         
2cfe0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2cff0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74  e if column part
2d000 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20   of PK */.  int 
2d010 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20  *pAutoinc       
2d020 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2d030 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2d040 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d  n is auto-increm
2d050 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ent */.);../*.**
2d060 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20   CAPI3REF: Load 
2d070 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31  An Extension {H1
2d080 32 36 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a  2600} <S20500>.*
2d090 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2d0a0 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2d0b0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2d0c0 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2d0d0 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2d0e0 20 7b 48 31 32 36 30 31 7d 20 54 68 65 20 73 71   {H12601} The sq
2d0f0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2d100 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2d110 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
2d120 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d an.**         
2d130 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
2d140 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
2d150 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
2d160 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zFile..**.** {H1
2d170 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20  2602} The entry 
2d180 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a  point is zProc..
2d190 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a  **.** {H12603} z
2d1a0 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69  Proc may be 0, i
2d1b0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2d1c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
2d1d0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20  ry point.**     
2d1e0 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f       defaults to
2d1f0 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
2d200 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a  ion_init"..**.**
2d210 20 7b 48 31 32 36 30 34 7d 20 54 68 65 20 73 71   {H12604} The sq
2d220 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2d230 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2d240 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a   shall return.**
2d250 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2d260 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2d270 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
2d280 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
2d290 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
2d2a0 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61  ** {H12605} If a
2d2b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
2d2c0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
2d2d0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
2d2e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d2f0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2d300 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  on()] interface 
2d310 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
2d320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
2d330 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
2d340 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2d350 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
2d360 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
2d370 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2d380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2d390 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61  ]. {END}  The ca
2d3a0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
2d3b0 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c  *          shoul
2d3c0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
2d3d0 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
2d3e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2d3f0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45  **.** {H12606} E
2d400 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2d410 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
2d420 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2d430 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
2d440 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2d450 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
2d460 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
2d470 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 68 65  **          othe
2d480 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77  rwise an error w
2d490 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2d4a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d4b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
2d4c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2d4d0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
2d4e0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2d4f0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
2d500 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
2d510 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
2d520 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
2d530 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
2d540 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
2d550 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
2d560 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
2d570 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
2d580 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
2d590 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
2d5a0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
2d5b0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
2d5c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
2d5d0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
2d5e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d5f0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2d600 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
2d610 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20  oading {H12620} 
2d620 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S20500>.**.** S
2d630 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
2d640 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
2d650 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
2d660 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
2d670 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
2d680 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
2d690 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
2d6a0 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
2d6b0 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
2d6c0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
2d6d0 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
2d6e0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
2d6f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
2d700 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
2d710 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
2d720 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2d730 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
2d740 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
2d750 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c  *.** Extension l
2d760 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
2d770 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
2d780 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a  cket #1863..**.*
2d790 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20  * {H12621} Call 
2d7a0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
2d7b0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
2d7c0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
2d7d0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20   onoff==1.**    
2d7e0 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78        to turn ex
2d7f0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2d800 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77  on and call it w
2d810 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20  ith onoff==0 to 
2d820 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2d830 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
2d840 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32  in..**.** {H1262
2d850 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  2} Extension loa
2d860 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
2d870 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73  efault..*/.int s
2d880 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2d890 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
2d8a0 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
2d8b0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
2d8c0 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
2d8d0 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
2d8e0 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d  ensions {H12640}
2d8f0 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20500>.**.** 
2d900 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20  This API can be 
2d910 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72  invoked at progr
2d920 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72  am startup in or
2d930 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a  der to register.
2d940 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ** one or more s
2d950 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
2d960 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74   extensions that
2d970 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62   will be availab
2d980 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77  le.** to all new
2d990 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d9a0 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a  ctions]. {END}.*
2d9b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2d9c0 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
2d9d0 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
2d9e0 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20  ion in an array 
2d9f0 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69  that is.** obtai
2da00 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2da10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66  3_malloc()].  If
2da20 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72   you run a memor
2da30 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a  y leak checker.*
2da40 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61  * on your progra
2da50 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73  m and it reports
2da60 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20   a leak because 
2da70 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c 20 69  of this array, i
2da80 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  nvoke.** [sqlite
2da90 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
2daa0 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
2dab0 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66  to shutdown to f
2dac0 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a  ree the memory..
2dad0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54  **.** {H12641} T
2dae0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  his function reg
2daf0 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73  isters an extens
2db00 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
2db10 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  that is.**      
2db20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
2db30 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  y invoked whenev
2db40 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61  er a new [databa
2db50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2db60 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 70  *          is op
2db70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
2db80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2db90 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2dba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2dbb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2dbc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2dbd0 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78  42} Duplicate ex
2dbe0 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
2dbf0 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
2dc00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2dc10 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70            multip
2dc20 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
2dc30 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
2dc40 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
2dc50 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69  .** {H12643} Thi
2dc60 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
2dc70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2dc80 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61  e extension in a
2dc90 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20  n array.**      
2dca0 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 74 61      that is obta
2dcb0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2dcc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
2dcd0 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74  .** {H12644} Aut
2dce0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2dcf0 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
2dd00 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69  ll threads..*/.i
2dd10 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  nt sqlite3_auto_
2dd20 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28  extension(void (
2dd30 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f  *xEntryPoint)(vo
2dd40 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id));../*.** CAP
2dd50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74  I3REF: Reset Aut
2dd60 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e  omatic Extension
2dd70 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30   Loading {H12660
2dd80 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20500>.**.**
2dd90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2dda0 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
2ddb0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2ddc0 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65  d automatic.** e
2ddd0 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d  xtensions. {END}
2dde0 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20    It undoes the 
2ddf0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
2de00 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
2de10 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2de20 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ] calls..**.** {
2de30 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e  H12661} This fun
2de40 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2de50 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2de60 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
2de70 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65       automatic e
2de80 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  xtensions..**.**
2de90 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 66   {H12662} This f
2dea0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2deb0 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
2dec0 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  sions in all thr
2ded0 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  eads..*/.void sq
2dee0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
2def0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
2df00 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  ;../*.****** EXP
2df10 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
2df20 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
2df30 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
2df40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
2df50 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
2df60 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
2df70 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
2df80 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
2df90 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
2dfa0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
2dfb0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
2dfc0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
2dfd0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
2dfe0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
2dff0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
2e000 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
2e010 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
2e020 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
2e030 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
2e040 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
2e050 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
2e060 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
2e070 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
2e080 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
2e090 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
2e0a0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
2e0b0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
2e0c0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
2e0d0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
2e0e0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
2e0f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e100 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
2e110 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
2e120 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2e130 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
2e140 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
2e150 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e160 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2e170 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
2e180 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
2e190 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2e1a0 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
2e1b0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
2e1c0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2e1d0 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31  Table Object {H1
2e1e0 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8000} <S20400>.*
2e1f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2e200 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
2e210 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2e220 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
2e230 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  L.**.** This str
2e240 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
2e250 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
2e260 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2e270 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
2e280 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2e290 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
2e2a0 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
2e2b0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
2e2c0 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
2e2d0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
2e2e0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
2e2f0 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  A virtual table 
2e300 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65  module is create
2e310 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20  d by filling in 
2e320 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  a persistent.** 
2e330 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2e340 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70   structure and p
2e350 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72  assing a pointer
2e360 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63   to that instanc
2e370 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  e.** to [sqlite3
2e380 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2e390 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
2e3a0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
2e3b0 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67 69 73 74  ]..** The regist
2e3c0 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
2e3d0 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
2e3e0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
2e3f0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
2e400 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
2e410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e420 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
2e430 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
2e440 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
2e450 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
2e460 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
2e470 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
2e480 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
2e490 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
2e4a0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2e4b0 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
2e4c0 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
2e4d0 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
2e4e0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
2e4f0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2e500 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
2e510 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
2e520 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2e530 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
2e540 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
2e550 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
2e560 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
2e570 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2e580 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
2e590 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
2e5a0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
2e5b0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2e5c0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
2e5d0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
2e5e0 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
2e5f0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
2e600 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
2e610 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
2e620 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
2e630 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2e640 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
2e650 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2e660 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
2e670 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2e680 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
2e690 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
2e6a0 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
2e6b0 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
2e6c0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
2e6d0 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
2e6e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2e6f0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
2e700 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
2e710 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
2e720 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2e730 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2e740 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
2e750 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
2e760 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2e770 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
2e780 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2e790 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
2e7a0 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
2e7b0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
2e7c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2e7d0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
2e7e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2e7f0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
2e800 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
2e810 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
2e820 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
2e830 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
2e840 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
2e850 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
2e860 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
2e870 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2e880 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
2e890 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2e8a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
2e8b0 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
2e8c0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2e8d0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
2e8e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2e8f0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
2e900 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
2e910 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
2e920 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
2e930 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
2e940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e950 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
2e960 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2e970 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e980 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
2e990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e9a0 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
2e9b0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
2e9c0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
2e9d0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
2e9e0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
2e9f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2ea00 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
2ea10 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
2ea20 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 30 34  n {H18100} <S204
2ea30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2ea40 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2ea50 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  nfo.** EXPERIMEN
2ea60 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
2ea70 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2ea80 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
2ea90 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
2eaa0 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
2eab0 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
2eac0 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
2ead0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
2eae0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
2eaf0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
2eb00 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2eb10 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
2eb20 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
2eb30 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
2eb40 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
2eb50 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
2eb60 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
2eb70 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
2eb80 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
2eb90 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
2eba0 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  fields..**.** Th
2ebb0 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
2ebc0 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
2ebd0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
2ebe0 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
2ebf0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63  rm:.**.** <pre>c
2ec00 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70  olumn OP expr</p
2ec10 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  re>.**.** where 
2ec20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
2ec30 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
2ec40 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 69  gt;=.  The parti
2ec50 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
2ec60 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61  s.** stored in a
2ec70 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
2ec80 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
2ec90 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
2eca0 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74  red in.** aConst
2ecb0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
2ecc0 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e    aConstraint[].
2ecd0 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
2ece0 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
2ecf0 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
2ed00 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
2ed10 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
2ed20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
2ed30 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
2ed40 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
2ed50 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  not..**.** The o
2ed60 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
2ed70 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
2ed80 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
2ed90 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
2eda0 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
2edb0 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
2edc0 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52  ions to the WHER
2edd0 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
2ede0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
2edf0 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
2ee00 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
2ee10 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
2ee20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
2ee30 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  e..** The aConst
2ee40 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
2ee50 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
2ee60 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
2ee70 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20   the correct.** 
2ee80 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20  form that refer 
2ee90 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
2eea0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
2eeb0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
2eec0 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  *.** Information
2eed0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
2eee0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
2eef0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
2ef00 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d  []..** Each term
2ef10 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
2ef20 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
2ef30 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
2ef40 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
2ef50 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
2ef60 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
2ef70 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
2ef80 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
2ef90 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
2efa0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
2efb0 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
2efc0 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
2efd0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
2efe0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
2eff0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f000 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
2f010 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
2f020 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
2f030 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
2f040 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43   in argv.  If aC
2f050 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
2f060 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
2f070 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
2f080 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
2f090 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
2f0a0 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
2f0b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
2f0c0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
2f0d0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
2f0e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75  .**.** The idxNu
2f0f0 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
2f100 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
2f110 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
2f120 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72   the.** [xFilter
2f130 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71  ] method..** [sq
2f140 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
2f150 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
2f160 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79  xPtr if and only
2f170 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72   iff.** needToFr
2f180 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
2f190 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
2f1a0 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
2f1b0 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
2f1c0 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e  om [xFilter]/[xN
2f1d0 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20  ext] will occur 
2f1e0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
2f1f0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
2f200 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
2f210 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
2f220 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
2f230 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
2f240 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
2f250 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
2f260 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
2f270 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
2f280 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
2f290 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
2f2a0 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
2f2b0 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
2f2c0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
2f2d0 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
2f2e0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
2f2f0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
2f300 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
2f310 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
2f320 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
2f330 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
2f340 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2f350 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
2f360 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
2f370 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
2f380 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
2f390 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
2f3a0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
2f3b0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
2f3c0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
2f3d0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
2f3e0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
2f3f0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
2f400 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
2f410 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
2f420 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
2f430 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
2f440 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
2f450 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
2f460 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
2f470 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
2f480 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
2f490 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
2f4a0 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
2f4b0 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
2f4c0 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
2f4d0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
2f4e0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
2f4f0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
2f500 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
2f510 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
2f520 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2f530 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
2f540 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
2f550 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
2f560 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
2f570 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
2f580 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
2f590 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
2f5a0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
2f5b0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
2f5c0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
2f5d0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
2f5e0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
2f5f0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
2f600 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
2f610 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
2f620 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
2f630 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
2f640 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
2f650 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
2f660 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2f670 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
2f680 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
2f690 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
2f6a0 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
2f6b0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
2f6c0 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
2f6d0 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
2f6e0 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
2f6f0 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
2f700 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
2f710 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
2f720 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
2f730 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20  intUsage;.  int 
2f740 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20  idxNum;         
2f750 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
2f760 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66   used to identif
2f770 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20  y the index */. 
2f780 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20   char *idxStr;  
2f790 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2f7a0 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20  tring, possibly 
2f7b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
2f7c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a  lite3_malloc */.
2f7d0 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
2f7e0 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20  IdxStr;      /* 
2f7f0 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e  Free idxStr usin
2f800 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
2f810 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e   if true */.  in
2f820 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  t orderByConsume
2f830 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  d;       /* True
2f840 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c   if output is al
2f850 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f  ready ordered */
2f860 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61  .  double estima
2f870 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a  tedCost;      /*
2f880 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20   Estimated cost 
2f890 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e  of using this in
2f8a0 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e  dex */.};.#defin
2f8b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2f8c0 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20  ONSTRAINT_EQ    
2f8d0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2f8e0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2f8f0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e  T_GT    4.#defin
2f900 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
2f910 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
2f920 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2f930 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
2f940 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69  T_LT    16.#defi
2f950 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2f960 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20  CONSTRAINT_GE   
2f970 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
2f980 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2f990 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a  INT_MATCH 64../*
2f9a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f9b0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
2f9c0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
2f9d0 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c  ation {H18200} <
2f9e0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20400>.** EXPER
2f9f0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
2fa00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
2fa10 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
2fa20 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
2fa30 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65  ble module] name
2fa40 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d 65  ..** Module name
2fa50 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
2fa60 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
2fa70 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
2fa80 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
2fa90 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20  ing the module, 
2faa0 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
2fab0 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
2fac0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
2fad0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
2fae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 6c  .**.** The modul
2faf0 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
2fb00 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
2fb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fb20 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
2fb30 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
2fb40 6d 65 74 65 72 2e 20 20 54 68 65 20 6e 61 6d 65  meter.  The name
2fb50 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
2fb60 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
2fb70 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
2fb80 74 65 72 2e 20 20 54 68 65 20 74 68 69 72 64 20  ter.  The third 
2fb90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
2fba0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
2fbb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fbc0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
2fbd0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
2fbe0 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70   The fourth.** p
2fbf0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2fc00 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20  rbitrary client 
2fc10 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
2fc20 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
2fc30 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ugh.** into the 
2fc40 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
2fc50 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
2fc60 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
2fc70 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20  table module.** 
2fc80 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75  when a new virtu
2fc90 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62  al table is be b
2fca0 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20  eing created or 
2fcb0 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a  reinitialized..*
2fcc0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2fcd0 61 63 65 20 68 61 73 20 65 78 61 63 74 6c 79 20  ace has exactly 
2fce0 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20  the same effect 
2fcf0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73  as calling.** [s
2fd00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2fd10 64 75 6c 65 5f 76 32 28 29 5d 20 77 69 74 68 20  dule_v2()] with 
2fd20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74 20 64 61  a NULL client da
2fd30 74 61 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ta destructor..*
2fd40 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
2fd50 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
2fd60 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
2fd70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2fd80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2fd90 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
2fda0 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
2fdb0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
2fdc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2fdd0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
2fde0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
2fdf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
2fe00 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
2fe10 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
2fe20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
2fe30 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
2fe40 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a          /* Cl
2fe50 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
2fe60 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
2fe70 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2fe80 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
2fe90 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
2fea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48  mplementation {H
2feb0 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18210} <S20400>.
2fec0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2fed0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2fee0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
2fef0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2ff00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
2ff10 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65   method,.** exce
2ff20 70 74 20 74 68 61 74 20 69 74 20 68 61 73 20 61  pt that it has a
2ff30 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 74 65  n extra paramete
2ff40 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a  r to specify .**
2ff50 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
2ff60 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 63  nction for the c
2ff70 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
2ff80 65 72 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  er.  SQLite will
2ff90 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
2ffa0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
2ffb0 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
2ffc0 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
2ffd0 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
2ffe0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
2fff0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
30000 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
30010 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
30020 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
30030 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
30040 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
30050 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
30060 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
30070 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
30080 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
30090 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
300a0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
300b0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
300c0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
300d0 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
300e0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
300f0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
30100 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20  ntData,         
30110 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
30120 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
30130 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
30140 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
30150 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
30160 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
30170 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
30180 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
30190 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
301a0 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20  Object {H18010} 
301b0 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
301c0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
301d0 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ab.** EXPERIMENT
301e0 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  AL.**.** Every [
301f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30200 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
30210 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
30220 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66  lass.** of the f
30230 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
30240 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  re to describe a
30250 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
30260 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
30270 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
30280 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
30290 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
302a0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
302b0 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
302c0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
302d0 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
302e0 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
302f0 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
30300 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
30310 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
30320 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
30330 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
30340 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  tions..**.** Vir
30350 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68  tual tables meth
30360 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65  ods can set an e
30370 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20  rror message by 
30380 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73  assigning a.** s
30390 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
303a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
303b0 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d  intf()] to zErrM
303c0 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
303d0 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
303e0 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
303f0 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
30400 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
30410 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
30420 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
30430 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
30440 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
30450 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
30460 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
30470 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
30480 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
30490 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
304a0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
304b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
304c0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
304d0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
304e0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
304f0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
30500 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
30510 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
30520 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
30530 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
30540 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
30550 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
30560 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
30570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30580 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
30590 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72   */.  char *zErr
305a0 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20  Msg;            
305b0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
305c0 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69  essage from sqli
305d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f  te3_mprintf() */
305e0 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
305f0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
30600 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
30610 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
30620 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
30630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30640 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75  Virtual Table Cu
30650 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31  rsor Object  {H1
30660 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8020} <S20400>.*
30670 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
30680 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
30690 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63  {virtual table c
306a0 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49  ursor}.** EXPERI
306b0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65  MENTAL.**.** Eve
306c0 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
306d0 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
306e0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
306f0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
30700 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  ** following str
30710 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69  ucture to descri
30720 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
30730 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a  point into the.*
30740 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
30750 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a  ] and are used.*
30760 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67  * to loop throug
30770 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
30780 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72  ble.  Cursors ar
30790 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
307a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
307b0 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78  module.xOpen | x
307c0 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  Open] method of 
307d0 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61  the module and a
307e0 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  re destroyed.** 
307f0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
30800 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20  module.xClose | 
30810 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20  xClose] method. 
30820 20 43 75 73 73 6f 72 73 20 61 72 65 20 75 73 65   Cussors are use
30830 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69  d.** by the [xFi
30840 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20  lter], [xNext], 
30850 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e  [xEof], [xColumn
30860 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20  ], and [xRowid] 
30870 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68  methods.** of th
30880 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
30890 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
308a0 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e  ation will defin
308b0 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  e.** the content
308c0 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72   of a cursor str
308d0 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69  ucture to suit i
308e0 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a  ts own needs..**
308f0 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c  .** This supercl
30900 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72  ass exists in or
30910 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69  der to define fi
30920 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73  elds of the curs
30930 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  or that.** are c
30940 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70  ommon to all imp
30950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f  lementations..*/
30960 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
30970 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
30980 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30990 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
309a0 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
309b0 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
309c0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
309d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
309e0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
309f0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
30a00 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
30a10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
30a20 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
30a30 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
30a40 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34  e {H18280} <S204
30a50 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
30a60 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78  TAL.**.** The [x
30a70 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
30a80 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
30a90 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  f a.** [virtual 
30aa0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61  table module] ca
30ab0 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ll this interfac
30ac0 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20  e.** to declare 
30ad0 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20  the format (the 
30ae0 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
30af0 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  pes of the colum
30b00 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69  ns) of.** the vi
30b10 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65  rtual tables the
30b20 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a  y implement..*/.
30b30 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
30b40 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
30b50 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c  declare_vtab(sql
30b60 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
30b70 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a  r *zSQL);../*.**
30b80 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c   CAPI3REF: Overl
30b90 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46  oad A Function F
30ba0 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  or A Virtual Tab
30bb0 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 30  le {H18300} <S20
30bc0 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  400>.** EXPERIME
30bd0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  NTAL.**.** Virtu
30be0 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72  al tables can pr
30bf0 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76  ovide alternativ
30c00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30c10 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  s of functions.*
30c20 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69  * using the [xFi
30c30 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68  ndFunction] meth
30c40 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  od of the [virtu
30c50 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
30c60 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61  .  .** But globa
30c70 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  l versions of th
30c80 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ose functions.**
30c90 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f   must exist in o
30ca0 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c  rder to be overl
30cb0 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  oaded..**.** Thi
30cc0 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
30cd0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
30ce0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
30cf0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
30d00 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
30d10 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
30d20 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
30d30 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
30d40 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
30d50 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
30d60 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
30d70 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20  ion is created. 
30d80 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
30d90 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
30da0 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
30db0 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
30dc0 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
30dd0 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
30de0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
30df0 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
30e00 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
30e10 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
30e20 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
30e30 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
30e40 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
30e50 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
30e60 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
30e70 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  le]..*/.SQLITE_E
30e80 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
30e90 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64  sqlite3_overload
30ea0 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65  _function(sqlite
30eb0 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
30ec0 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e  zFuncName, int n
30ed0 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  Arg);../*.** The
30ee0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
30ef0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30f00 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65  mechanism define
30f10 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70  d above (back up
30f20 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74  .** to a comment
30f30 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69   remarkably simi
30f40 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29  lar to this one)
30f50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
30f60 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
30f70 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
30f80 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
30f90 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
30fa0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
30fb0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
30fc0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
30fd0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
30fe0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
30ff0 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
31000 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
31010 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
31020 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
31030 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
31040 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
31050 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
31060 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
31070 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
31080 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a  mment..**.******
31090 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
310a0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
310b0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
310c0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
310d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
310e0 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
310f0 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31  An Open BLOB {H1
31100 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7800} <S30230>.*
31110 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f  * KEYWORDS: {BLO
31120 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20  B handle} {BLOB 
31130 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41  handles}.**.** A
31140 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
31150 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
31160 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
31170 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73  B on which.** [s
31180 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
31190 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
311a0 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20  LOB I/O] can be 
311b0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62  performed..** Ob
311c0 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
311d0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
311e0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
311f0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
31200 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
31210 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
31220 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
31230 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
31240 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
31250 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
31260 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
31270 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
31280 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
31290 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
312a0 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  BLOB..** The [sq
312b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
312c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
312d0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
312e0 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79  f the BLOB in by
312f0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
31300 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
31310 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
31320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31330 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
31340 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
31350 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 33 30  /O {H17810} <S30
31360 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  230>.**.** This 
31370 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
31380 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20   a [BLOB handle 
31390 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65  | handle] to the
313a0 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a   BLOB located.**
313b0 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
313c0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
313d0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
313e0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
313f0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
31400 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61  he same BLOB tha
31410 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
31420 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
31430 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
31440 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
31450 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
31460 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a  [rowid] = iRow;.
31470 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a  ** </pre> {END}.
31480 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61  **.** If the fla
31490 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  gs parameter is 
314a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
314b0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
314c0 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e  d for read.** an
314d0 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20  d write access. 
314e0 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
314f0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
31500 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73  d for read acces
31510 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
31520 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
31530 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20  name is not the 
31540 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f  filename that co
31550 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61  ntains.** the da
31560 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65  tabase but rathe
31570 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  r the symbolic n
31580 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
31590 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  ase that.** is a
315a0 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65  ssigned when the
315b0 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
315c0 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
315d0 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68  TACH]..** For th
315e0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
315f0 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61  file, the databa
31600 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e  se name is "main
31610 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74  "..** For TEMP t
31620 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
31630 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
31640 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  p"..**.** On suc
31650 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
31660 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
31670 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20  d the new [BLOB 
31680 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
31690 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62  en.** to *ppBlob
316a0 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  . Otherwise an [
316b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
316c0 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42  eturned and *ppB
316d0 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  lob is set.** to
316e0 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74   be a null point
316f0 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  er..** This func
31700 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64  tion sets the [d
31710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31720 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  on] error code a
31730 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
31740 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
31750 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
31760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
31770 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61  rmsg()] and rela
31780 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ted.** functions
31790 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
317a0 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c   *ppBlob variabl
317b0 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74  e is always init
317c0 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20  ialized in a.** 
317d0 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69  way that makes i
317e0 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65  t safe to invoke
317f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
31800 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c  lose()] on *ppBl
31810 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ob.** regardless
31820 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20   of the success 
31830 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
31840 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
31850 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 61  * If the row tha
31860 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  t a BLOB handle 
31870 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64  points to is mod
31880 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b  ified by an.** [
31890 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45  UPDATE], [DELETE
318a0 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e  ], or by [ON CON
318b0 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65  FLICT] side-effe
318c0 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  cts.** then the 
318d0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d  BLOB handle is m
318e0 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65  arked as "expire
318f0 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74  d"..** This is t
31900 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d  rue if any colum
31910 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20  n of the row is 
31920 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20  changed, even a 
31930 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20  column.** other 
31940 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65  than the one the
31950 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
31960 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c  open on..** Call
31970 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  s to [sqlite3_bl
31980 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
31990 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
319a0 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65  te()] for.** a e
319b0 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64  xpired BLOB hand
319c0 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  le fail with an 
319d0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
319e0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
319f0 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 65  * Changes writte
31a00 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72  n into a BLOB pr
31a10 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ior to the BLOB 
31a20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74  expiring are not
31a30 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 20  .** rollback by 
31a40 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  the expiration o
31a50 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63  f the BLOB.  Suc
31a60 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65  h changes will e
31a70 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d  ventually.** com
31a80 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73  mit if the trans
31a90 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73  action continues
31aa0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
31ab0 2a 2a 0a 2a 2a 20 55 73 65 20 74 68 65 20 5b 73  **.** Use the [s
31ac0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
31ad0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  s()] interface t
31ae0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
31af0 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  size of.** the o
31b00 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 54 68 65  pened blob.  The
31b10 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
31b20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
31b30 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 75 6e  ed by this.** un
31b40 64 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  derface.  Use th
31b50 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
31b60 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
31b70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
31b80 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68  * blob..**.** Th
31b90 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31ba0 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20  zeroblob()] and 
31bb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31bc0 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65  zeroblob()] inte
31bd0 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68  rfaces.** and th
31be0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f  e built-in [zero
31bf0 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69  blob] SQL functi
31c00 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  on can be used, 
31c10 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74  if desired,.** t
31c20 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74  o create an empt
31c30 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62  y, zero-filled b
31c40 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20  lob in which to 
31c50 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73  read or write us
31c60 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65  ing.** this inte
31c70 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20  rface..**.** To 
31c80 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65  avoid a resource
31c90 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65   leak, every ope
31ca0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
31cb0 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c  should eventuall
31cc0 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64  y.** be released
31cd0 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   by a call to [s
31ce0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
31cf0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  e()]..**.** Requ
31d00 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
31d10 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b  7813] [H17814] [
31d20 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d  H17816] [H17819]
31d30 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32   [H17821] [H1782
31d40 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  4].*/.int sqlite
31d50 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
31d60 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
31d70 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
31d80 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
31d90 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31da0 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
31db0 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
31dc0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
31dd0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
31de0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
31df0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20  PI3REF: Close A 
31e00 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37  BLOB Handle {H17
31e10 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  830} <S30230>.**
31e20 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70  .** Closes an op
31e30 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
31e40 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20  ..**.** Closing 
31e50 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75  a BLOB shall cau
31e60 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
31e70 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
31e80 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65  mmit.** if there
31e90 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c   are no other BL
31ea0 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20  OBs, no pending 
31eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31ec0 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  nts, and the.** 
31ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31ee0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63  ion is in [autoc
31ef0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20  ommit mode]..** 
31f00 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
31f10 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
31f20 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
31f30 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
31f40 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
31f50 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
31f60 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a   they will fit..
31f70 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68  **.** Closing th
31f80 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72  e BLOB often for
31f90 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a  ces the changes.
31fa0 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61  ** out to disk a
31fb0 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f  nd so if any I/O
31fc0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74   errors occur, t
31fd0 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  hey will likely 
31fe0 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20  occur.** at the 
31ff0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c  time when the BL
32000 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41  OB is closed.  A
32010 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  ny errors that o
32020 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63  ccur during.** c
32030 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72  losing are repor
32040 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72  ted as a non-zer
32050 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a  o return value..
32060 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69  **.** The BLOB i
32070 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
32080 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
32090 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
320a0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
320b0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
320c0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
320d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  ed..**.** Callin
320e0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
320f0 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74  ith a null point
32100 65 72 20 28 77 68 69 63 68 20 61 73 20 77 6f 75  er (which as wou
32110 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
32120 2a 20 62 79 20 66 61 69 6c 65 64 20 63 61 6c 6c  * by failed call
32130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
32140 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20  b_open()]) is a 
32150 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
32160 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
32170 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20  ts:.** [H17833] 
32180 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39  [H17836] [H17839
32190 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
321a0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
321b0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
321c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
321d0 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
321e0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48   An Open BLOB {H
321f0 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17840} <S30230>.
32200 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68  **.** Returns th
32210 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
32220 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65  of the BLOB acce
32230 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a  ssible via the .
32240 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ** successfully 
32250 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e  opened [BLOB han
32260 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79  dle] in its only
32270 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 0a   argument.  The.
32280 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
32290 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
322a0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
322b0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
322c0 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
322d0 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
322e0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
322f0 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
32300 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32310 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
32320 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
32330 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
32340 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
32350 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
32360 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
32370 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
32380 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
32390 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
323a0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
323b0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
323c0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
323d0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
323e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
323f0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
32400 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
32410 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
32420 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  r..**.** Require
32430 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34  ments:.** [H1784
32440 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  3].*/.int sqlite
32450 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
32460 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
32470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32480 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
32490 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
324a0 6c 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 30  ly {H17850} <S30
324b0 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  230>.**.** This 
324c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
324d0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
324e0 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
324f0 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
32500 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
32510 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
32520 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
32530 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
32540 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
32550 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
32560 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
32570 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ffset..**.** If 
32580 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
32590 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79  s less than N by
325a0 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
325b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a   of the BLOB,.**
325c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
325d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
325e0 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
325f0 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65    If N or iOffse
32600 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  t is.** less tha
32610 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f  n zero, [SQLITE_
32620 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
32630 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
32640 73 20 72 65 61 64 2e 0a 2a 2a 20 54 68 65 20 73  s read..** The s
32650 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20  ize of the blob 
32660 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
32670 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
32680 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
32690 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
326a0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
326b0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
326c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
326d0 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  * An attempt to 
326e0 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70  read from an exp
326f0 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
32700 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
32710 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
32720 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
32730 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
32740 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
32750 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
32760 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
32770 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
32780 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
32790 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
327a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
327b0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
327c0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
327d0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
327e0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
327f0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
32800 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
32810 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
32820 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
32830 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
32840 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
32850 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
32860 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
32870 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
32880 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
32890 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
328a0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
328b0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
328c0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
328d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
328e0 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2a  lob_write()]..**
328f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
32900 3a 0a 2a 2a 20 5b 48 31 37 38 35 33 5d 20 5b 48  :.** [H17853] [H
32910 31 37 38 35 36 5d 20 5b 48 31 37 38 35 39 5d 20  17856] [H17859] 
32920 5b 48 31 37 38 36 32 5d 20 5b 48 31 37 38 36 33  [H17862] [H17863
32930 5d 20 5b 48 31 37 38 36 35 5d 20 5b 48 31 37 38  ] [H17865] [H178
32940 36 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  68].*/.int sqlit
32950 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c  e3_blob_read(sql
32960 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69  ite3_blob *, voi
32970 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74  d *Z, int N, int
32980 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
32990 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 74  * CAPI3REF: Writ
329a0 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
329b0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
329c0 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 33   {H17870} <S3023
329d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
329e0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
329f0 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74  o write data int
32a00 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  o an open [BLOB 
32a10 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a  handle] from a.*
32a20 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
32a30 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65  d buffer. N byte
32a40 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f  s of data are co
32a50 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  pied from the bu
32a60 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74  ffer Z.** into t
32a70 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
32a80 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
32a90 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
32aa0 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e  If the [BLOB han
32ab0 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74  dle] passed as t
32ac0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32ad0 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64  t was not opened
32ae0 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20   for.** writing 
32af0 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (the flags param
32b00 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
32b10 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61  _blob_open()] wa
32b20 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73  s zero),.** this
32b30 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
32b40 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  s [SQLITE_READON
32b50 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  LY]..**.** This 
32b60 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c  function may onl
32b70 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e  y modify the con
32b80 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f  tents of the BLO
32b90 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  B; it is.** not 
32ba0 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72  possible to incr
32bb0 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ease the size of
32bc0 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68   a BLOB using th
32bd0 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f 66  is API..** If of
32be0 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20  fset iOffset is 
32bf0 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65  less than N byte
32c00 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f  s from the end o
32c10 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b  f the BLOB,.** [
32c20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
32c30 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
32c40 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
32c50 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  .  If N is.** le
32c60 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
32c70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
32c80 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
32c90 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
32ca0 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  ** The size of t
32cb0 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e  he BLOB (and hen
32cc0 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
32cd0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
32ce0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
32cf0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
32d00 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
32d10 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
32d20 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74  ce..**.** An att
32d30 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f  empt to write to
32d40 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
32d50 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
32d60 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
32d70 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
32d80 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 73  _ABORT].  Writes
32d90 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61   to the BLOB tha
32da0 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65  t occurred.** be
32db0 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68  fore the [BLOB h
32dc0 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61  andle] expired a
32dd0 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61  re not rolled ba
32de0 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70  ck by the.** exp
32df0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68  iration of the h
32e00 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66  andle, though of
32e10 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68   course those ch
32e20 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68  anges might.** h
32e30 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69  ave been overwri
32e40 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74  tten by the stat
32e50 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72  ement that expir
32e60 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ed the BLOB hand
32e70 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65  le.** or by othe
32e80 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74  r independent st
32e90 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
32ea0 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
32eb0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
32ec0 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  d..** Otherwise,
32ed0 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
32ee0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
32ef0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
32f00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
32f10 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   This routine on
32f20 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42  ly works on a [B
32f30 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63  LOB handle] whic
32f40 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74  h has been creat
32f50 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72  ed.** by a prior
32f60 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
32f70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
32f80 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68  b_open()] and wh
32f90 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62  ich has not.** b
32fa0 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73  een closed by [s
32fb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
32fc0 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61  e()].  Passing a
32fd0 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72  ny other pointer
32fe0 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72   in.** to this r
32ff0 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69  outine results i
33000 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  n undefined and 
33010 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
33020 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a  able behavior..*
33030 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33040 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33050 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  d()]..**.** Requ
33060 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
33070 37 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b  7873] [H17874] [
33080 48 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 5d  H17875] [H17876]
33090 20 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 37   [H17877] [H1787
330a0 39 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 37  9] [H17882] [H17
330b0 38 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d  885].** [H17888]
330c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
330d0 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74  blob_write(sqlit
330e0 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74  e3_blob *, const
330f0 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
33100 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
33110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33120 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73  Virtual File Sys
33130 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31  tem Objects {H11
33140 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a  200} <S20100>.**
33150 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
33160 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
33170 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
33180 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
33190 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
331a0 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
331b0 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
331c0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
331d0 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20  m.  Most SQLite 
331e0 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
331f0 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66   a.** single def
33200 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73  ault VFS that is
33210 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
33220 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
33230 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  er..** New VFSes
33240 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
33250 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20  ed and existing 
33260 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72  VFSes can be unr
33270 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68  egistered..** Th
33280 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
33290 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
332a0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ded..**.** The s
332b0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
332c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
332d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
332e0 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73   a VFS given its
332f0 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20   name..** Names 
33300 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69  are case sensiti
33310 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65  ve..** Names are
33320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
33330 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
33340 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  ** If there is n
33350 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20  o match, a NULL 
33360 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
33370 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e  ned..** If zVfsN
33380 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
33390 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
333a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
333b0 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72  .** New VFSes ar
333c0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
333d0 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  h sqlite3_vfs_re
333e0 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63  gister()..** Eac
333f0 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65  h new VFS become
33400 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  s the default VF
33410 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c  S if the makeDfl
33420 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a  t flag is set..*
33430 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63  * The same VFS c
33440 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
33450 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
33460 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a  without injury..
33470 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78  ** To make an ex
33480 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20  isting VFS into 
33490 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c  the default VFS,
334a0 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61   register it aga
334b0 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d  in.** with the m
334c0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74  akeDflt flag set
334d0 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72  .  If two differ
334e0 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74  ent VFSes with t
334f0 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20  he.** same name 
33500 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20  are registered, 
33510 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
33520 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61  undefined.  If a
33530 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73  .** VFS is regis
33540 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d  tered with a nam
33550 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f  e that is NULL o
33560 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
33570 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  g,.** then the b
33580 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
33590 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65  ined..**.** Unre
335a0 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74  gister a VFS wit
335b0 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  h the sqlite3_vf
335c0 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69  s_unregister() i
335d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20  nterface..** If 
335e0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
335f0 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
33600 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
33610 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
33620 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
33630 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
33640 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
33650 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ry..**.** Requir
33660 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32  ements:.** [H112
33670 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 48 31  03] [H11206] [H1
33680 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b  1209] [H11212] [
33690 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31 38 5d  H11215] [H11218]
336a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
336b0 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
336c0 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
336d0 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
336e0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
336f0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  r(sqlite3_vfs*, 
33700 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69  int makeDflt);.i
33710 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  nt sqlite3_vfs_u
33720 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  nregister(sqlite
33730 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  3_vfs*);../*.** 
33740 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65  CAPI3REF: Mutexe
33750 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 30 30  s {H17000} <S200
33760 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00>.**.** The SQ
33770 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
33780 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
33790 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63  r thread.** sync
337a0 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f  hronization. Tho
337b0 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74  ugh they are int
337c0 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e  ended for intern
337d0 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
337e0 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c  ite, code that l
337f0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
33800 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74  ite is.** permit
33810 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f  ted to use any o
33820 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ..**.** The SQLi
33840 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63  te source code c
33850 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65  ontains multiple
33860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
33870 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74  .** of these mut
33880 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e  ex routines.  An
33890 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70   appropriate imp
338a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
338b0 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d  s selected autom
338c0 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70  atically at comp
338d0 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66  ile-time.  The f
338e0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c  ollowing.** impl
338f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20  ementations are 
33900 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
33910 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a   SQLite core:.**
33920 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
33930 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
33940 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  OS2.** <li>   SQ
33950 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
33960 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
33970 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a  ITE_MUTEX_W32.**
33980 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
33990 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75  UTEX_NOOP.** </u
339a0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
339b0 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69  ITE_MUTEX_NOOP i
339c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
339d0 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e   a set of routin
339e0 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  es.** that does 
339f0 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20  no real locking 
33a00 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61  and is appropria
33a10 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a  te for use in.**
33a20 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64   a single-thread
33a30 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  ed application. 
33a40 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
33a50 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45  X_OS2,.** SQLITE
33a60 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20  _MUTEX_PTHREAD, 
33a70 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
33a80 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74  _W32 implementat
33a90 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72  ions.** are appr
33aa0 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
33ab0 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61  on OS/2, Unix, a
33ac0 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a  nd Windows..**.*
33ad0 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63  * If SQLite is c
33ae0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
33af0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50   SQLITE_MUTEX_AP
33b00 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f  PDEF preprocesso
33b10 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e  r.** macro defin
33b20 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49  ed (with "-DSQLI
33b30 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d  TE_MUTEX_APPDEF=
33b40 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74  1"), then no mut
33b50 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
33b60 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64  tion is included
33b70 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
33b80 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  y. In this case 
33b90 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
33ba0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
33bb0 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d   custom mutex im
33bc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69  plementation usi
33bd0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
33be0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
33bf0 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71  option of the sq
33c00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66  lite3_config() f
33c10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72  unction.** befor
33c20 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  e calling sqlite
33c30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f  3_initialize() o
33c40 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c  r any other publ
33c50 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66  ic sqlite3_.** f
33c60 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c  unction that cal
33c70 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
33c80 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b  alize()..**.** {
33c90 48 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69  H17011} The sqli
33ca0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
33cb0 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61  ) routine alloca
33cc0 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74  tes a new.** mut
33cd0 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ex and returns a
33ce0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
33cf0 7b 48 31 37 30 31 32 7d 20 49 66 20 69 74 20 72  {H17012} If it r
33d00 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
33d10 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
33d20 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
33d30 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b   be allocated. {
33d40 48 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a  H17013} SQLite.*
33d50 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74  * will unwind it
33d60 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75  s stack and retu
33d70 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31  rn an error. {H1
33d80 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65  7014} The argume
33d90 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
33da0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
33db0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
33dc0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
33dd0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
33de0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
33df0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
33e00 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
33e10 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
33e20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
33e30 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
33e40 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
33e50 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
33e60 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
33e70 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
33e80 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
33e90 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
33ea0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
33eb0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
33ec0 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
33ed0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
33ee0 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  RU2.** </ul>.**.
33ef0 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 65 20  ** {H17015} The 
33f00 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
33f10 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65  nts cause sqlite
33f20 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
33f30 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e  to create.** a n
33f40 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e  ew mutex.  The n
33f50 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75  ew mutex is recu
33f60 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54  rsive when SQLIT
33f70 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
33f80 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74  E.** is used but
33f90 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79   not necessarily
33fa0 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f   so when SQLITE_
33fb0 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73  MUTEX_FAST is us
33fc0 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65  ed. {END}.** The
33fd0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
33fe0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
33ff0 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
34000 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
34010 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
34020 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
34030 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
34040 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
34050 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48  not want to.  {H
34060 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74  17016} But SQLit
34070 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75  e will only requ
34080 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20  est a recursive 
34090 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65  mutex in.** case
340a0 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c  s where it reall
340b0 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45  y needs one.  {E
340c0 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20  ND} If a faster 
340d0 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75  non-recursive mu
340e0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
340f0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
34100 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70  le on the host p
34110 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74  latform, the mut
34120 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ex subsystem.** 
34130 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63  might return suc
34140 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73  h a mutex in res
34150 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f  ponse to SQLITE_
34160 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a  MUTEX_FAST..**.*
34170 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 65 20 6f  * {H17017} The o
34180 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
34190 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
341a0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
341b0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
341c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
341d0 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
341e0 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20  g mutex. {END}  
341f0 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65  Four static mute
34200 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
34210 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
34220 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
34230 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
34240 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
34250 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
34260 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
34270 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
34280 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
34290 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
342a0 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
342b0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
342c0 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
342d0 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
342e0 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
342f0 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
34300 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
34310 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
34320 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
34330 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  VE..**.** {H1701
34340 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20  8} Note that if 
34350 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d  one of the dynam
34360 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74  ic mutex paramet
34370 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45  ers (SQLITE_MUTE
34380 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c  X_FAST.** or SQL
34390 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
343a0 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 65  IVE) is used the
343b0 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  n sqlite3_mutex_
343c0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72  alloc().** retur
343d0 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d  ns a different m
343e0 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61  utex on every ca
343f0 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 75  ll.  {H17034} Bu
34400 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
34410 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c  .** mutex types,
34420 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20   the same mutex 
34430 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65  is returned on e
34440 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68  very call that h
34450 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  as.** the same t
34460 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  ype number..**.*
34470 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20 73  * {H17019} The s
34480 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
34490 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c  e() routine deal
344a0 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f  locates a previo
344b0 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  usly.** allocate
344c0 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e  d dynamic mutex.
344d0 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74 65   {H17020} SQLite
344e0 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
344f0 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
34500 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
34510 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
34520 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 65  es. {A17021} The
34530 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
34540 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a   must not be in.
34550 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79  ** use when they
34560 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
34570 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65 6d  . {A17022} Attem
34580 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
34590 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
345a0 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
345b0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
345c0 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 51  ior. {H17023} SQ
345d0 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c  Lite never deall
345e0 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74  ocates.** a stat
345f0 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a  ic mutex. {END}.
34600 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34610 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20  3_mutex_enter() 
34620 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
34630 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73  x_try() routines
34640 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65   attempt.** to e
34650 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b 48  nter a mutex. {H
34660 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 65  17024} If anothe
34670 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65  r thread is alre
34680 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d  ady within the m
34690 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  utex,.** sqlite3
346a0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77  _mutex_enter() w
346b0 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71  ill block and sq
346c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
346d0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
346e0 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48   SQLITE_BUSY. {H
346f0 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c 69  17025}  The sqli
34700 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
34710 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34720 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a  s [SQLITE_OK].**
34730 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
34740 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 36   entry.  {H17026
34750 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65  } Mutexes create
34760 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  d using.** SQLIT
34770 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
34780 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64  E can be entered
34790 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
347a0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
347b0 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20  ad..** {H17027} 
347c0 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68  In such cases th
347d0 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74  e,.** mutex must
347e0 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71   be exited an eq
347f0 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  ual number of ti
34800 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68  mes before anoth
34810 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e  er thread.** can
34820 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 38   enter.  {A17028
34830 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  } If the same th
34840 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
34850 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
34860 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
34870 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
34880 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
34890 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31  ndefined..** {H1
348a0 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  7029} SQLite wil
348b0 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a  l never exhibit.
348c0 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72  ** such behavior
348d0 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20   in its own use 
348e0 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a  of mutexes..**.*
348f0 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28  * Some systems (
34900 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e  for example, Win
34910 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20  dows 95) do not 
34920 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72  support the oper
34930 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ation.** impleme
34940 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  nted by sqlite3_
34950 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e  mutex_try().  On
34960 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20   those systems, 
34970 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
34980 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  y().** will alwa
34990 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ys return SQLITE
349a0 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30 7d  _BUSY.  {H17030}
349b0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
349c0 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a   only ever uses.
349d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
349e0 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74  _try() as an opt
349f0 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69  imization so thi
34a00 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  s is acceptable 
34a10 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
34a20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 71 6c  {H17031} The sql
34a30 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
34a40 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73  () routine exits
34a50 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61   a mutex that wa
34a60 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
34a70 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73  entered by the s
34a80 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41 31  ame thread.  {A1
34a90 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 69  7032} The behavi
34aa0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
34ab0 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ed if the mutex 
34ac0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
34ad0 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a   entered by the.
34ae0 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  ** calling threa
34af0 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72  d or is not curr
34b00 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e  ently allocated.
34b10 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 74    {H17033} SQLit
34b20 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20  e will.** never 
34b30 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d  do either. {END}
34b40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72  .**.** If the ar
34b50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
34b60 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c  3_mutex_enter(),
34b70 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
34b80 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69  ry(), or.** sqli
34b90 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
34ba0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
34bb0 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68  ter, then all th
34bc0 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ree routines.** 
34bd0 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73  behave as no-ops
34be0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34bf0 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  : [sqlite3_mutex
34c00 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71  _held()] and [sq
34c10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
34c20 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  eld()]..*/.sqlit
34c30 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65  e3_mutex *sqlite
34c40 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e  3_mutex_alloc(in
34c50 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
34c60 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69  _mutex_free(sqli
34c70 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
34c80 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
34c90 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75  enter(sqlite3_mu
34ca0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
34cb0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c  e3_mutex_try(sql
34cc0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
34cd0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
34ce0 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d  _leave(sqlite3_m
34cf0 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
34d00 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d  API3REF: Mutex M
34d10 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48  ethods Object {H
34d20 31 37 31 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a  17120} <S20130>.
34d30 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
34d40 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
34d50 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
34d60 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ure defines the 
34d70 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e  low-level routin
34d80 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c  es.** used to al
34d90 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d  locate and use m
34da0 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73  utexes..**.** Us
34db0 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75  ually, the defau
34dc0 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  lt mutex impleme
34dd0 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65  ntations provide
34de0 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a  d by SQLite are.
34df0 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68  ** sufficient, h
34e00 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 72 20  owever the user 
34e10 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f  has the option o
34e20 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 61  f substituting a
34e30 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65   custom.** imple
34e40 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70  mentation for sp
34e50 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79  ecialized deploy
34e60 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73  ments or systems
34e70 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74   for which SQLit
34e80 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72  e.** does not pr
34e90 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 6c 65  ovide a suitable
34ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
34eb0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74   In this case, t
34ec0 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74  he user.** creat
34ed0 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73  es and populates
34ee0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
34ef0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 74  this structure t
34f00 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c  o pass.** to sql
34f10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c  ite3_config() al
34f20 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 51  ong with the [SQ
34f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
34f40 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64  X] option..** Ad
34f50 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69  ditionally, an i
34f60 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
34f70 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 65  structure can be
34f80 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f   used as an.** o
34f90 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 77  utput variable w
34fa0 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65  hen querying the
34fb0 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20   system for the 
34fc0 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a  current mutex.**
34fd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
34fe0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
34ff0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
35000 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a  EX] option..**.*
35010 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74  * The xMutexInit
35020 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
35030 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
35040 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
35050 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
35060 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  m initialization
35070 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
35080 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e  initialize() fun
35090 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30  ction..** {H1700
350a0 31 7d 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69  1} The xMutexIni
350b0 74 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  t routine shall 
350c0 62 65 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c  be called by SQL
350d0 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ite once for eac
350e0 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63  h.** effective c
350f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35100 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a  initialize()]..*
35110 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 45  *.** The xMutexE
35120 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65  nd method define
35130 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
35140 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ure is invoked a
35150 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73  s.** part of sys
35160 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20  tem shutdown by 
35170 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  the sqlite3_shut
35180 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e  down() function.
35190 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   The.** implemen
351a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  tation of this m
351b0 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65  ethod is expecte
351c0 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c  d to release all
351d0 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20   outstanding.** 
351e0 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e  resources obtain
351f0 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20  ed by the mutex 
35200 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e  methods implemen
35210 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c  tation, especial
35220 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61  ly.** those obta
35230 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74  ined by the xMut
35240 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b  exInit method. {
35250 48 31 37 30 30 33 7d 20 54 68 65 20 78 4d 75 74  H17003} The xMut
35260 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72  exEnd().** inter
35270 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 69 6e  face shall be in
35280 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
35290 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
352a0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
352b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61  ..**.** The rema
352c0 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68  ining seven meth
352d0 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74  ods defined by t
352e0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78  his structure (x
352f0 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78  MutexAlloc,.** x
35300 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65  MutexFree, xMute
35310 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72  xEnter, xMutexTr
35320 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20  y, xMutexLeave, 
35330 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a  xMutexHeld and.*
35340 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  * xMutexNotheld)
35350 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66   implement the f
35360 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
35370 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c  ces (respectivel
35380 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y):.**.** <ul>.*
35390 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
353a0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
353b0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
353c0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
353d0 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a  x_free()] </li>.
353e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
353f0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
35400 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
35410 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
35420 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a  ex_try()] </li>.
35430 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
35440 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
35450 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
35460 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
35470 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  ex_held()] </li>
35480 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
35490 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
354a0 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  ld()] </li>.** <
354b0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  /ul>.**.** The o
354c0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69  nly difference i
354d0 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69  s that the publi
354e0 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75  c sqlite3_XXX fu
354f0 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74  nctions enumerat
35500 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65  ed.** above sile
35510 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20  ntly ignore any 
35520 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74  invocations that
35530 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69   pass a NULL poi
35540 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  nter instead.** 
35550 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78  of a valid mutex
35560 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70   handle. The imp
35570 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35580 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69  the methods defi
35590 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73  ned.** by this s
355a0 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74  tructure are not
355b0 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e   required to han
355c0 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74  dle this case, t
355d0 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66  he results.** of
355e0 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   passing a NULL 
355f0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
35600 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78  of a valid mutex
35610 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65   handle are unde
35620 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69  fined.** (i.e. i
35630 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  t is acceptable 
35640 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d  to provide an im
35650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
35660 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a  t segfaults if.*
35670 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  * it is passed a
35680 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a   NULL pointer)..
35690 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
356a0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
356b0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
356c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73  mutex_methods;.s
356d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
356e0 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  tex_methods {.  
356f0 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74  int (*xMutexInit
35700 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28  )(void);.  int (
35710 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64  *xMutexEnd)(void
35720 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74  );.  sqlite3_mut
35730 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f  ex *(*xMutexAllo
35740 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20  c)(int);.  void 
35750 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71  (*xMutexFree)(sq
35760 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
35770 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45    void (*xMutexE
35780 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75  nter)(sqlite3_mu
35790 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  tex *);.  int (*
357a0 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74  xMutexTry)(sqlit
357b0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76  e3_mutex *);.  v
357c0 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76  oid (*xMutexLeav
357d0 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e)(sqlite3_mutex
357e0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
357f0 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33  texHeld)(sqlite3
35800 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
35810 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64   (*xMutexNotheld
35820 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
35830 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *);.};../*.** CA
35840 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65  PI3REF: Mutex Ve
35850 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69  rification Routi
35860 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32  nes {H17080} <S2
35870 30 31 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a  0130> <S30800>.*
35880 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35890 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
358a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
358b0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
358c0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
358d0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
358e0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
358f0 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20  ments. {H17081} 
35900 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a  The SQLite core.
35910 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68  ** never uses th
35920 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63  ese routines exc
35930 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73  ept inside an as
35940 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69  sert() and appli
35950 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61  cations.** are a
35960 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77  dvised to follow
35970 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65   the lead of the
35980 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d   core.  {H17082}
35990 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a   The core only.*
359a0 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65  * provides imple
359b0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74  mentations for t
359c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68  hese routines wh
359d0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
359e0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51  d.** with the SQ
359f0 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e  LITE_DEBUG flag.
35a00 20 20 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72    {A17087} Exter
35a10 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
35a20 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
35a30 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
35a40 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
35a50 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
35a60 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
35a70 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
35a80 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
35a90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  ned..**.** {H170
35aa0 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  83} These routin
35ab0 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  es should return
35ac0 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74   true if the mut
35ad0 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75  ex in their argu
35ae0 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20  ment.** is held 
35af0 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73  or not held, res
35b00 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68  pectively, by th
35b10 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
35b20 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d  ..**.** {X17084}
35b30 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
35b40 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
35b50 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
35b60 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
35b70 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
35b80 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
35b90 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
35ba0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
35bb0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
35bc0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
35bd0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
35be0 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
35bf0 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
35c00 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
35c10 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
35c20 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
35c30 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
35c40 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
35c50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d  ..**.** {H17085}
35c60 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   If the argument
35c70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
35c80 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55  x_held() is a NU
35c90 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
35ca0 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73  ** the routine s
35cb0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20  hould return 1. 
35cc0 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d   {END} This seem
35cd0 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74  s counter-intuit
35ce0 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65  ive since.** cle
35cf0 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63  arly the mutex c
35d00 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66  annot be held if
35d10 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69   it does not exi
35d20 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20  st.  But the.** 
35d30 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d  the reason the m
35d40 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78  utex does not ex
35d50 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74  ist is because t
35d60 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a  he build is not.
35d70 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73  ** using mutexes
35d80 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74  .  And we do not
35d90 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74   want the assert
35da0 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  () containing th
35db0 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  e.** call to sql
35dc0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
35dd0 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20  ) to fail, so a 
35de0 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
35df0 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70  is.** the approp
35e00 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64  riate thing to d
35e10 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65  o.  {H17086} The
35e20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
35e30 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65  otheld().** inte
35e40 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73  rface should als
35e50 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20  o return 1 when 
35e60 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  given a NULL poi
35e70 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nter..*/.int sql
35e80 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
35e90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
35ea0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
35eb0 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74  ex_notheld(sqlit
35ec0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
35ed0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
35ee0 65 78 20 54 79 70 65 73 20 7b 48 31 37 30 30 31  ex Types {H17001
35ef0 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H17000>.**.**
35f00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
35f10 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
35f20 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
35f30 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
35f40 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
35f50 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
35f60 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
35f70 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74   The set of stat
35f80 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63  ic mutexes may c
35f90 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53  hange from one S
35fa0 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f  QLite release to
35fb0 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
35fc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
35fd0 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75   override the bu
35fe0 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67  ilt-in mutex log
35ff0 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72  ic must be.** pr
36000 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d  epared to accomm
36010 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c  odate additional
36020 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
36030 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
36040 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20  TE_MUTEX_FAST   
36050 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
36060 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
36070 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
36080 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
36090 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
360a0 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66  MASTER    2.#def
360b0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
360c0 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20  _STATIC_MEM     
360d0 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    3  /* sqlite3_
360e0 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66  malloc() */.#def
360f0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
36100 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20  _STATIC_MEM2    
36110 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44    4  /* NOT USED
36120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
36130 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36140 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20  OPEN      4  /* 
36150 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e  sqlite3BtreeOpen
36160 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
36170 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
36180 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f  C_PRNG      5  /
36190 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  * sqlite3_random
361a0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
361b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
361c0 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f  C_LRU       6  /
361d0 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
361e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
361f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
36200 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c  RU2      7  /* l
36210 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
36220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36230 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75   Retrieve the mu
36240 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61  tex for a databa
36250 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se connection {H
36260 31 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a  17002} <H17000>.
36270 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
36280 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
36290 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69  ointer the [sqli
362a0 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
362b0 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61  t that .** seria
362c0 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20  lizes access to 
362d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
362e0 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20  nnection] given 
362f0 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
36300 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72  ** when the [thr
36310 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
36320 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49  Serialized..** I
36330 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  f the [threading
36340 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65   mode] is Single
36350 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69  -thread or Multi
36360 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69  -thread then thi
36370 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  s.** routine ret
36380 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
36390 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
363a0 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64  mutex *sqlite3_d
363b0 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a  b_mutex(sqlite3*
363c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
363d0 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f  EF: Low-Level Co
363e0 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73  ntrol Of Databas
363f0 65 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d  e Files {H11300}
36400 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
36410 7b 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71  {H11301} The [sq
36420 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
36430 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ol()] interface 
36440 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63  makes a direct c
36450 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46  all to the.** xF
36460 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
36470 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
36480 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
36490 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
364a0 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69  .** with a parti
364b0 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69  cular database i
364c0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
364d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
364e0 2e 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a  . {H11302} The.*
364f0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * name of the da
36500 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61  tabase is the na
36510 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74  me assigned to t
36520 68 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74  he database by t
36530 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c  he.** <a href="l
36540 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22  ang_attach.html"
36550 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20  >ATTACH</a> SQL 
36560 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65  command that ope
36570 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ned the.** datab
36580 61 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f  ase. {H11303} To
36590 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69   control the mai
365a0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
365b0 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d   use the name "m
365c0 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c  ain".** or a NUL
365d0 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33  L pointer. {H113
365e0 30 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e  04} The third an
365f0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
36600 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ers to this rout
36610 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  ine.** are passe
36620 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75  d directly throu
36630 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64  gh to the second
36640 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d   and third param
36650 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20  eters of.** the 
36660 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
36670 68 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54  hod.  {H11305} T
36680 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
36690 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  of the xFileCont
366a0 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65  rol.** method be
366b0 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e  comes the return
366c0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
366d0 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  outine..**.** {H
366e0 31 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65  11306} If the se
366f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
36700 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f  zDbName) does no
36710 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65  t match the name
36720 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20   of any.** open 
36730 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
36740 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  hen SQLITE_ERROR
36750 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48   is returned. {H
36760 31 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f  11307} This erro
36770 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74  r.** code is not
36780 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20   remembered and 
36790 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61  will not be reca
367a0 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  lled by [sqlite3
367b0 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f  _errcode()].** o
367c0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
367d0 67 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54  g()]. {A11308} T
367e0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46  he underlying xF
367f0 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
36800 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20  d might.** also 
36810 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52  return SQLITE_ER
36820 52 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54  ROR.  {A11309} T
36830 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74  here is no way t
36840 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65  o distinguish be
36850 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f  tween.** an inco
36860 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e  rrect zDbName an
36870 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  d an SQLITE_ERRO
36880 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68  R return from th
36890 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
368a0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
368b0 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  hod. {END}.**.**
368c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
368d0 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
368e0 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  TE].*/.int sqlit
368f0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
36900 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
36910 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69  char *zDbName, i
36920 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt op, void*);..
36930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36940 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63  Testing Interfac
36950 65 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38  e {H11400} <S308
36960 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
36970 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
36980 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ol() interface i
36990 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  s used to read o
369a0 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73  ut internal.** s
369b0 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61  tate of SQLite a
369c0 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75  nd to inject fau
369d0 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  lts into SQLite 
369e0 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70  for testing.** p
369f0 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69  urposes.  The fi
36a00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
36a10 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f   an operation co
36a20 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  de that determin
36a30 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  es.** the number
36a40 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f  , meaning, and o
36a50 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20  peration of all 
36a60 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
36a70 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  eters..**.** Thi
36a80 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
36a90 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70  ot for use by ap
36aa0 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20  plications.  It 
36ab0 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a  exists solely.**
36ac0 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74   for verifying t
36ad0 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61  he correct opera
36ae0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
36af0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70  te library.  Dep
36b00 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77  ending.** on how
36b10 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
36b20 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c  ary is compiled,
36b30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
36b40 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e  might not exist.
36b50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
36b60 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74  ls of the operat
36b70 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72  ion codes, their
36b80 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70   meanings, the p
36b90 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65  arameters.** the
36ba0 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74  y take, and what
36bb0 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c   they do are all
36bc0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
36bd0 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
36be0 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73  e..** Unlike mos
36bf0 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  t of the SQLite 
36c00 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69  API, this functi
36c10 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  on is not guaran
36c20 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61  teed to.** opera
36c30 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20  te consistently 
36c40 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
36c50 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
36c60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73  .int sqlite3_tes
36c70 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70  t_control(int op
36c80 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
36c90 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67  API3REF: Testing
36ca0 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61   Interface Opera
36cb0 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34  tion Codes {H114
36cc0 31 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a  10} <H11400>.**.
36cd0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
36ce0 74 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64  ts are the valid
36cf0 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20   operation code 
36d00 70 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a  parameters used.
36d10 2a 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ** as the first 
36d20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
36d30 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
36d40 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  l()]..**.** Thes
36d50 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  e parameters and
36d60 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20   their meanings 
36d70 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
36d80 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74  hange.** without
36d90 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20   notice.  These 
36da0 76 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74  values are for t
36db0 65 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20  esting purposes 
36dc0 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  only..** Applica
36dd0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
36de0 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
36df0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
36e00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
36e10 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  test_control()] 
36e20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
36e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
36e40 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20  TCTRL_PRNG_SAVE 
36e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
36e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36e70 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45  TESTCTRL_PRNG_RE
36e80 53 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20  STORE           
36e90 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
36ea0 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
36eb0 5f 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20  _RESET          
36ec0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
36ed0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42  QLITE_TESTCTRL_B
36ee0 49 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20  ITVEC_TEST      
36ef0 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
36f00 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
36f10 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20  L_FAULT_INSTALL 
36f20 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
36f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
36f40 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c  CTRL_BENIGN_MALL
36f50 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a  OC_HOOKS     10.
36f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
36f70 45 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f  ESTCTRL_PENDING_
36f80 42 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20  BYTE            
36f90 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
36fa0 45 5f 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52  E_TESTCTRL_ASSER
36fb0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
36fc0 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
36fd0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c  LITE_TESTCTRL_AL
36fe0 57 41 59 53 20 20 20 20 20 20 20 20 20 20 20 20  WAYS            
36ff0 20 20 20 20 20 20 31 33 0a 0a 2f 2a 0a 2a 2a 20        13../*.** 
37000 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65  CAPI3REF: SQLite
37010 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20   Runtime Status 
37020 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30  {H17200} <S60200
37030 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
37040 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  L.**.** This int
37050 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
37060 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69  o retrieve runti
37070 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d  me status inform
37080 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74  ation.** about t
37090 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f  he preformance o
370a0 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70  f SQLite, and op
370b0 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65  tionally to rese
370c0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67  t various.** hig
370d0 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54  hwater marks.  T
370e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
370f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
37100 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
37110 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74  specific paramet
37120 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20  er to measure.  
37130 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67  Recognized integ
37140 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20  er codes.** are 
37150 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c  of the form [SQL
37160 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52  ITE_STATUS_MEMOR
37170 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f  Y_USED | SQLITE_
37180 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20  STATUS_...]..** 
37190 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  The current valu
371a0 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  e of the paramet
371b0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  er is returned i
371c0 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a  nto *pCurrent..*
371d0 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 72 65  * The highest re
371e0 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20  corded value is 
371f0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69  returned in *pHi
37200 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 65  ghwater.  If the
37210 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73  .** resetFlag is
37220 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
37230 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76  highest record v
37240 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66  alue is reset af
37250 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  ter.** *pHighwat
37260 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53  er is written. S
37270 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 64  ome parameters d
37280 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65  o not record the
37290 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75   highest.** valu
372a0 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61  e.  For those pa
372b0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68  rameters.** noth
372c0 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69  ing is written i
372d0 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20  nto *pHighwater 
372e0 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c 61  and the resetFla
372f0 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  g is ignored..**
37300 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72   Other parameter
37310 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68  s record only th
37320 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
37330 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72   and not the cur
37340 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20  rent.** value.  
37350 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72  For these latter
37360 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68   parameters noth
37370 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69  ing is written i
37380 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a  nto *pCurrent..*
37390 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
373a0 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
373b0 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
373c0 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  nd a non-zero.**
373d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
373e0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
373f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
37400 74 68 72 65 61 64 73 61 66 65 20 62 75 74 20 69  threadsafe but i
37410 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54  s not atomic.  T
37420 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a  his routine can.
37430 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20  ** called while 
37440 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72  other threads ar
37450 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61  e running the sa
37460 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20  me or different 
37470 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66  SQLite.** interf
37480 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74  aces.  However t
37490 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
374a0 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20  ed in *pCurrent 
374b0 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  and.** *pHighwat
374c0 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73  er reflect the s
374d0 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20  tatus of SQLite 
374e0 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69  at different poi
374f0 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61  nts in time.** a
37500 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  nd it is possibl
37510 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
37520 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e  hread might chan
37530 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ge the parameter
37540 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74  .** in between t
37550 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70  he times when *p
37560 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69  Current and *pHi
37570 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74  ghwater are writ
37580 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ten..**.** See a
37590 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
375a0 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51  _status()].*/.SQ
375b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
375c0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  L int sqlite3_st
375d0 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74  atus(int op, int
375e0 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20   *pCurrent, int 
375f0 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74  *pHighwater, int
37600 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f   resetFlag);.../
37610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
37620 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73  tatus Parameters
37630 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30   {H17250} <H1720
37640 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
37650 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  AL.**.** These i
37660 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
37670 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f   designate vario
37680 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74  us run-time stat
37690 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  us parameters.**
376a0 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74   that can be ret
376b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
376c0 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a  3_status()]..**.
376d0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
376e0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d  QLITE_STATUS_MEM
376f0 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a  ORY_USED</dt>.**
37700 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
37710 74 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65  ter is the curre
37720 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  nt amount of mem
37730 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a  ory checked out.
37740 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37750 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74  3_malloc()], eit
37760 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20  her directly or 
37770 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  indirectly.  The
37780 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75  .** figure inclu
37790 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74  des calls made t
377a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
377b0 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c  c()] by the appl
377c0 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69  ication.** and i
377d0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75  nternal memory u
377e0 73 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69  sage by the SQLi
377f0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72  te library.  Scr
37800 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  atch memory.** c
37810 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51  ontrolled by [SQ
37820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
37830 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61  TCH] and auxilia
37840 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a  ry page-cache.**
37850 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c   memory controll
37860 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  ed by [SQLITE_CO
37870 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20  NFIG_PAGECACHE] 
37880 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
37890 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d  in.** this param
378a0 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e  eter.  The amoun
378b0 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  t returned is th
378c0 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c  e sum of the all
378d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73  ocation.** sizes
378e0 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20   as reported by 
378f0 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64  the xSize method
37900 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   in [sqlite3_mem
37910 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a  _methods].</dd>.
37920 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
37930 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53  _STATUS_MALLOC_S
37940 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IZE</dt>.** <dd>
37950 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72  This parameter r
37960 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65  ecords the large
37970 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  st memory alloca
37980 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20  tion request.** 
37990 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
379a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
379b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
379c0 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a  ()] (or their.**
379d0 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61   internal equiva
379e0 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68  lents).  Only th
379f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
37a00 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67   in the.** *pHig
37a10 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72  hwater parameter
37a20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61   to [sqlite3_sta
37a30 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74  tus()] is of int
37a40 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20  erest.  .** The 
37a50 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e  value written in
37a60 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74  to the *pCurrent
37a70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e   parameter is un
37a80 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
37a90 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
37aa0 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f  TATUS_PAGECACHE_
37ab0 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  USED</dt>.** <dd
37ac0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
37ad0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37ae0 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64  er of pages used
37af0 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   out of the.** [
37b00 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79  pagecache memory
37b10 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74   allocator] that
37b20 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   was configured 
37b30 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54  using .** [SQLIT
37b40 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
37b50 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c  HE].  The.** val
37b60 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69  ue returned is i
37b70 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20  n pages, not in 
37b80 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bytes.</dd>.**.*
37b90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41  * <dt>SQLITE_STA
37ba0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56  TUS_PAGECACHE_OV
37bb0 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  ERFLOW</dt>.** <
37bc0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
37bd0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
37be0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
37bf0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
37c00 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20  llocation which 
37c10 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61  could not be sta
37c20 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b  tisfied by the [
37c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
37c40 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66  GECACHE].** buff
37c50 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72  er and where for
37c60 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20  ced to overflow 
37c70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
37c80 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72  oc()].  The.** r
37c90 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e  eturned value in
37ca0 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f  cludes allocatio
37cb0 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77  ns that overflow
37cc0 65 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a  ed because they.
37cd0 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72  ** where too lar
37ce0 67 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61  ge (they were la
37cf0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73  rger than the "s
37d00 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  z" parameter to.
37d10 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
37d20 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e  G_PAGECACHE]) an
37d30 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68  d allocations th
37d40 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65  at overflowed be
37d50 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63  cause.** no spac
37d60 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68  e was left in th
37d70 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64  e page cache.</d
37d80 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
37d90 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
37da0 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  ACHE_SIZE</dt>.*
37db0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
37dc0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
37dd0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
37de0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
37df0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
37e00 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72  [pagecache memor
37e10 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f  y allocator].  O
37e20 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65  nly the value re
37e30 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a  turned in the.**
37e40 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72   *pHighwater par
37e50 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
37e60 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20  e3_status()] is 
37e70 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a  of interest.  .*
37e80 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74  * The value writ
37e90 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43  ten into the *pC
37ea0 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  urrent parameter
37eb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   is undefined.</
37ec0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
37ed0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
37ee0 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a  TCH_USED</dt>.**
37ef0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
37f00 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20  ter returns the 
37f10 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61  number of alloca
37f20 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f  tions used out o
37f30 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63  f the.** [scratc
37f40 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  h memory allocat
37f50 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75  or] configured u
37f60 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  sing.** [SQLITE_
37f70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e  CONFIG_SCRATCH].
37f80 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
37f90 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63  rned is in alloc
37fa0 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69  ations, not.** i
37fb0 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20  n bytes.  Since 
37fc0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
37fd0 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e  may only have on
37fe0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
37ff0 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64  tion.** outstand
38000 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69  ing at time, thi
38010 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f  s parameter also
38020 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d   reports the num
38030 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a  ber of threads.*
38040 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20  * using scratch 
38050 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61  memory at the sa
38060 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a  me time.</dd>.**
38070 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
38080 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56  TATUS_SCRATCH_OV
38090 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  ERFLOW</dt>.** <
380a0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
380b0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
380c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
380d0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a   scratch memory.
380e0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68  ** allocation wh
380f0 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  ich could not be
38100 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74   statisfied by t
38110 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
38120 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75  G_SCRATCH].** bu
38130 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66  ffer and where f
38140 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f  orced to overflo
38150 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  w to [sqlite3_ma
38160 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61  lloc()].  The va
38170 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lues.** returned
38180 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f   include overflo
38190 77 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72  ws because the r
381a0 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74  equested allocat
381b0 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c  ion was too.** l
381c0 61 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20  arger (that is, 
381d0 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75  because the requ
381e0 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e  ested allocation
381f0 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e   was larger than
38200 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72   the.** "sz" par
38210 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54  ameter to [SQLIT
38220 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
38230 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e  ]) and because n
38240 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
38250 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61  .** slots were a
38260 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64  vailable..** </d
38270 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
38280 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
38290 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  CH_SIZE</dt>.** 
382a0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
382b0 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  er records the l
382c0 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c  argest memory al
382d0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
382e0 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  .** handed to [s
382f0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
38300 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20  locator].  Only 
38310 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
38320 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48  ed in the.** *pH
38330 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74  ighwater paramet
38340 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  er to [sqlite3_s
38350 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69  tatus()] is of i
38360 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68  nterest.  .** Th
38370 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20  e value written 
38380 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65  into the *pCurre
38390 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nt parameter is 
383a0 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
383b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
383c0 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53  _STATUS_PARSER_S
383d0 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  TACK</dt>.** <dd
383e0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
383f0 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70  records the deep
38400 65 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b  est parser stack
38410 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a  .  It is only.**
38420 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53   meaningful if S
38430 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
38440 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d  d with [YYTRACKM
38450 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f  AXSTACKDEPTH].</
38460 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  dd>.** </dl>.**.
38470 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61  ** New status pa
38480 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20  rameters may be 
38490 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20  added from time 
384a0 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66  to time..*/.#def
384b0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
384c0 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20  S_MEMORY_USED   
384d0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
384e0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50   SQLITE_STATUS_P
384f0 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20  AGECACHE_USED   
38500 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
38510 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
38520 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20  CACHE_OVERFLOW  
38530 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
38540 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
38550 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a  _USED         3.
38560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
38570 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56  TATUS_SCRATCH_OV
38580 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65  ERFLOW     4.#de
38590 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
385a0 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20  US_MALLOC_SIZE  
385b0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
385c0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
385d0 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20  PARSER_STACK    
385e0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
385f0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47  QLITE_STATUS_PAG
38600 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20  ECACHE_SIZE     
38610 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
38620 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
38630 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38  H_SIZE         8
38640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38650 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
38660 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31  ction Status {H1
38670 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  7500} <S60200>.*
38680 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
38690 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
386a0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ace is used to r
386b0 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20  etrieve runtime 
386c0 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69  status informati
386d0 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73  on .** about a s
386e0 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20  ingle [database 
386f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
38700 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38710 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   is the.** datab
38720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
38730 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65  bject to be inte
38740 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73  rrogated.  The s
38750 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a  econd argument.*
38760 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  * is the paramet
38770 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74  er to interrogat
38780 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74  e.  Currently, t
38790 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20  he only allowed 
387a0 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65  value.** for the
387b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
387c0 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53  r is [SQLITE_DBS
387d0 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f  TATUS_LOOKASIDE_
387e0 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69  USED]..** Additi
387f0 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c  onal options wil
38800 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20  l likely appear 
38810 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
38820 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
38830 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20  .** The current 
38840 76 61 6c 75 65 20 6f 66 20 74 68 65