/ Hex Artifact Content
Login

Artifact 718a026b4cf3c766fc7ac5ff582faa60324b116c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 34 30 20 32 30 30 39 2f 30  n,v 1.440 2009/0
05f0: 34 2f 30 36 20 31 35 3a 35 35 3a 30 34 20 64 72  4/06 15:55:04 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4190: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41a0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
41c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
41d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
41e0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
41f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4200: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4210: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
4220: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4230: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
4240: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
4260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4270: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
4280: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4290: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42a0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
42b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
42c0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
42d0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
42e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
42f0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4300: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
4320: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4330: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
4340: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4350: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4360: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
4370: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4380: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4390: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
43a0: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
43b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
43c0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
43e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
43f0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
4400: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4410: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4420: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4430: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4440: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4450: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4460: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4470: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
4480: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
4490: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
44a0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
44b0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
44c0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
44d0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
44e0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
44f0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4500: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4510: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4520: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4530: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4540: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4550: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4560: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4570: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4580: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
45a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
45b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
45c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
45d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
45e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
45f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4600: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4610: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4620: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4630: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4640: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4650: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4660: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4670: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4680: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4690: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
46a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
46b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
46c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
46d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
46e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
46f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4700: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4710: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4720: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4730: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4740: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4750: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4760: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4770: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4780: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4790: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
47a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
47b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47c0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
47d0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
47e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47f0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4800: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4810: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4820: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4830: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4850: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4860: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4880: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4890: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
48a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48b0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
48c0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
48d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48e0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
48f0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4910: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4920: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4940: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4950: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4970: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4980: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4990: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
49a0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
49b0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
49c0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
49d0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
49e0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
49f0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4a00: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4a10: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4a20: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4a30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4a40: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4a50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4a60: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4a80: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4a90: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4aa0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4ab0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ad0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4ae0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4af0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4b20: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4b30: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4b40: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4b50: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4b60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4b70: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4b80: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4b90: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4ba0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4bb0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4bc0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4bd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4be0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4bf0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4c00: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4c10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4c20: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4c30: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4c40: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4c50: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4c60: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4c70: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4c80: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4c90: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4ca0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4cb0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4cc0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4cd0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4ce0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4cf0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4d00: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4d10: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4d20: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4d30: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4d40: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4d50: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4d60: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4d70: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4d80: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4d90: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4da0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4db0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4dc0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4dd0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4df0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4e00: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4e10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4e20: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4e30: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4e40: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4e50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4e60: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4e70: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4e80: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4e90: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4ea0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4eb0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ec0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
4ed0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
4ee0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
4ef0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
4f00: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
4f10: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
4f20: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
4f30: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
4f40: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
4f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
4f60: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
4f70: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
4f80: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
4f90: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
4fa0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
4fb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
4fd0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
4fe0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
4ff0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5000: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5010: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5020: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5030: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5050: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5060: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
5070: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
5080: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
5090: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
50a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
50b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
50c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
50d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
50f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5100: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5110: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5120: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5130: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5140: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5150: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5160: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
5170: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
5180: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
5190: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
51a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
51b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
51c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
51d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
51e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
51f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5200: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5210: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5220: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5230: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5240: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5250: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5260: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5270: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5280: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5290: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
52a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
52b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
52c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
52d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
52e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
52f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5300: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5310: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5320: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5330: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5340: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5350: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5360: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5370: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5380: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
53a0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
53c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
53e0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
53f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5400: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5410: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5420: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5430: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5440: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5450: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5460: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5470: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5480: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5490: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
54a0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
54b0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
54c0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
54d0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
54e0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
54f0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5500: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5510: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5520: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5530: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5540: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5550: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5560: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5570: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5580: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5590: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
55a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
55b0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
55c0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
55d0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
55e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
55f0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5600: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5610: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5620: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5630: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5640: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5650: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5660: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5670: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5680: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5690: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
56a0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
56b0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
56c0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
56d0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
56e0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
56f0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5700: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5710: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5720: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5730: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5740: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5750: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5760: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5770: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5780: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5790: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
57a0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
57b0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
57c0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
57d0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
57e0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
57f0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5810: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5820: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5830: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5840: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5860: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5870: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5880: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5890: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
58a0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
58b0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
58c0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
58d0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
58e0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
58f0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5900: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5910: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5920: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5930: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5940: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5950: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5960: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5970: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5980: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5990: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
59a0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
59b0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
59c0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
59d0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
59e0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
59f0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5a20: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5a40: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a80: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5aa0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ac0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b00: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b20: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5b40: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5b50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5b60: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5b70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5b80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b90: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5ba0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5bb0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5bc0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5be0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5bf0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5c00: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5c10: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5c20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5c30: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5c40: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5c50: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5c60: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5c70: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5c80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5c90: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5ca0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5cb0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5cc0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5cd0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5ce0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5cf0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5d00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5d10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5d20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5d30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5d40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5d50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5d70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5d80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5d90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5da0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5db0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5dc0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5dd0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5de0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5df0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5e00: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5e10: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5e20: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5e30: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
5e40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5e50: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
5e60: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5e70: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5e80: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5e90: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5ea0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5eb0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ec0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
5ed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
5ef0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5f00: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
5f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
5f20: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
5f30: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
5f40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5f50: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
5f60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
5f70: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
5f80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
5f90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
5fa0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5fb0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
5fc0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
5fd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
5fe0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
5ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6000: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6010: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6020: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6030: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6040: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6050: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6060: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6070: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6080: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6090: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
60a0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
60b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
60d0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
60e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
60f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6100: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6110: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6120: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6130: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6140: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6150: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6160: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6170: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6180: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6190: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
61a0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
61b0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
61c0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
61d0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
61e0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
61f0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6200: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6210: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6220: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6230: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6240: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6250: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6270: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6280: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6290: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
62a0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
62b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
62c0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
62d0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
62e0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
62f0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6300: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6310: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6320: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6330: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6340: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6350: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6360: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6370: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6380: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6390: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
63a0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
63b0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
63c0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
63d0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
63e0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
63f0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6400: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6410: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6420: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6430: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6440: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6450: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6460: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6470: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6480: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
64a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
64b0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
64c0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
64d0: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
64f0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6500: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6510: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6520: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6530: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6540: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6550: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6560: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6570: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6580: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6590: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
65a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
65b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
65c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
65d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
65e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
65f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6600: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6610: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6620: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6630: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6640: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6650: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6660: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6680: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6690: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
66a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
66b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
66c0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
66d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
66e0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
66f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6700: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6710: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6720: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6730: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6740: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6750: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6760: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6770: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6780: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6790: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
67a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
67b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
67c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
67d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
67e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
67f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6800: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6810: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6820: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6830: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6840: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6850: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6860: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6870: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6880: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6890: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
68a0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
68b0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
68c0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
68d0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
68e0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
68f0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6900: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6910: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6920: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6930: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6940: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6950: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6960: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6970: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6980: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6990: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
69a0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
69b0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
69c0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
69d0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
69e0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
69f0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6a00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6a10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6a20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6a30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6a40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6a50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6a60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6a70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6a80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6a90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6aa0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6ab0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6ac0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6ad0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6ae0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6af0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6b00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6b10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6b20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6b30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6b40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6b50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6b60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6b70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6b80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6b90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6ba0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6bb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6bc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6bd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6be0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6bf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6c00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6c10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6c20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6c30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6c40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6c50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6c60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6c70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6c80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6c90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6ca0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6cb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6cc0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6cd0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6ce0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6cf0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6d00: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6d10: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6d20: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6d30: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6d40: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6d50: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6d60: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6d70: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6d80: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6d90: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6da0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6db0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6dc0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6dd0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6de0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6df0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6e00: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6e10: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6e20: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6e30: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6e40: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6e50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6e60: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6e70: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6e80: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6e90: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6ea0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6eb0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ec0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
6ed0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
6ee0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
6ef0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
6f00: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
6f10: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
6f20: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
6f30: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
6f40: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
6f50: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
6f60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
6f70: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
6f80: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
6f90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6fa0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
6fb0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
6fc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6fd0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
6fe0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
6ff0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7000: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7010: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7020: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7040: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7050: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7060: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7070: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7080: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
70a0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
70b0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
70c0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
70d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
70e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
70f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7100: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7110: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7120: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7130: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7150: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7160: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7170: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7180: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7190: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
71a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
71b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
71c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
71d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
71e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
71f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7210: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7220: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7230: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7240: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7250: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7260: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7270: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7280: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7290: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
72a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
72b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
72c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
72d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
72e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
72f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7300: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7310: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7320: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7330: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7340: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7350: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7360: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7370: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7380: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7390: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
73a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
73b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
73c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
73d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
73e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
73f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7400: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7410: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7420: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7430: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7440: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7450: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7460: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7470: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7480: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7490: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
74a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
74b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
74c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
74d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
74e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
74f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7500: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7510: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7520: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7530: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7540: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7550: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7560: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7570: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7580: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7590: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
75a0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
75b0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
75c0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
75d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
75e0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
75f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
7600: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
7610: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7620: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
7630: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
7640: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
7650: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
7660: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
7670: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
7680: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
7690: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
76a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
76b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
76c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
76d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
76e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
76f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
7700: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7710: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
7720: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
7730: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
7740: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
7750: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it in..**.** The
7760: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7770: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7780: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7790: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
77a0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
77b0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
77c0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
77d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
77e0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
77f0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
7800: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
7810: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
7820: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
7830: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
7840: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
7850: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
7860: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
7870: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
7880: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7890: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
78a0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
78b0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
78c0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
78d0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
78e0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
78f0: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7900: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
7910: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
7920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
7930: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
7940: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
7950: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
7960: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
7970: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
7980: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
7990: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
79a0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
79b0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
79c0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
79d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
79e0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
79f0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
7a00: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
7a10: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
7a20: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
7a30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
7a40: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
7a50: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
7a60: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
7a70: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
7a80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
7a90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
7aa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
7ab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
7ac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
7ad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
7ae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7af0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
7b00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
7b10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
7b20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
7b30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
7b40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
7b50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
7b60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
7b70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
7b80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
7b90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
7ba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
7bb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
7bc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
7bd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
7be0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
7bf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
7c00: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
7c10: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7c20: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
7c30: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
7c40: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
7c50: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65  time..**.*/.type
7c60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7c70: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
7c80: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
7c90: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
7ca0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
7cb0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
7cc0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
7cd0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
7ce0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
7cf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
7d00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
7d10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
7d20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
7d30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
7d40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
7d50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
7d60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
7d70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
7d80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
7d90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
7da0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
7db0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
7dc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
7dd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
7de0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
7df0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
7e00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
7e10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
7e20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7e30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
7e40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
7e60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
7e70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
7e80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
7e90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ea0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
7eb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
7ec0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
7ed0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ee0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
7ef0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
7f00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7f10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7f20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7f30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7f40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7f50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
7f60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
7f70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7f80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
7f90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7fb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7fc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7fd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
7fe0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
8000: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
8010: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8020: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8030: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8040: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
8050: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8060: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8070: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8080: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8090: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
80a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
80b0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
80c0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
80d0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
80e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
80f0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
8100: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
8110: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8120: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
8130: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
8140: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
8150: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
8160: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
8170: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
8180: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8190: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
81a0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48  ss VFS method {H
81b0: 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a  11190} <H11140>.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
81d0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
81e0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
81f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
8200: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
8210: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
8220: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
8230: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
8240: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
8250: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
8260: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
8270: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
8280: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
8290: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
82a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
82b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
82c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
82d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
82e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
82f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8300: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
8310: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
8320: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8330: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8340: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8350: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  le..** With SQLI
8360: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
8370: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8380: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
8390: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
83a0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64   readable..*/.#d
83b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83c0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
83d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
83f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8400: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
8410: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    2../*.** CAPI3
8420: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
8430: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
8440: 72 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30  ry {H10130} <S20
8450: 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  000><S30100>.**.
8460: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8470: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8480: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
8490: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
84a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
84b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
84c0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
84d0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
84e0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
84f0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
8500: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
8540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
8550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
8560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
8590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
85a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
85b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
85c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
85d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
85e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
85f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
8600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8610: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
8620: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
8630: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
8640: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
8650: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
8660: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
8670: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
8680: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
8690: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
86a0: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  gs, sqlite3_init
86b0: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69  ialize() shall i
86c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
86d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
86e0: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f  ilarly, sqlite3_
86f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68  shutdown().** sh
8700: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  all invoke sqlit
8710: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
8720: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8730: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8740: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
8750: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
8760: 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f  ss..** If for so
8770: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
8780: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8790: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
87a0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
87b0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
87c0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
87d0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
87e0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
87f0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
8800: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
8810: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
8820: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
8830: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
8840: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8850: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
8860: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
8870: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
8880: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
8890: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
88a0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
88b0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
88c0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
88d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
88e0: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
88f0: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
8900: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
8910: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
8920: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
8930: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
8940: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
8950: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
8960: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
8970: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
8980: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
8990: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
89a0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65  * already.  Howe
89b0: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
89c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
89d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
89e0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
89f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8a00: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
8a10: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
8a20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8a30: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
8a40: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
8a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
8a60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8a70: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
8a80: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
8a90: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
8aa0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
8ab0: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
8ac0: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
8ad0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
8ae0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
8af0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
8b00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8b10: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
8b20: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
8b30: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
8b40: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
8b50: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
8b60: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
8b70: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
8b80: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
8b90: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
8ba0: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
8bb0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
8bc0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
8bd0: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
8be0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
8bf0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
8c00: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
8c10: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
8c20: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
8c30: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
8c40: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
8c50: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
8c60: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
8c70: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
8c80: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
8c90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
8ca0: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
8cb0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
8cc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
8cd0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
8ce0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
8cf0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
8d00: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
8d10: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
8d20: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
8d30: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
8d40: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
8d50: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
8d60: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
8d70: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
8d80: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
8d90: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
8da0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
8db0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
8dc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
8dd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
8de0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
8df0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
8e00: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
8e10: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
8e20: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
8e30: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
8e40: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
8e50: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
8e60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8e70: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
8e80: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
8e90: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
8ea0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
8eb0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
8ec0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
8ed0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
8ee0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
8ef0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
8f00: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
8f10: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
8f20: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
8f30: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
8f40: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
8f50: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
8f60: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
8f70: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
8f80: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
8f90: 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c  r unix, windows,
8fa0: 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65   or os/2..** Whe
8fb0: 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  n built for othe
8fc0: 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69  r platforms (usi
8fd0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
8fe0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
8ff0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
9000: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
9010: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
9020: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
9030: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9040: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9050: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
9060: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
9070: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
9080: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
9090: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
90a0: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
90b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
90c0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
90d0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
90e0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
90f0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
9100: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
9110: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
9120: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
9130: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
9140: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
9150: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9160: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
9170: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
9180: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9190: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
91a0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
91b0: 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30   {H14100} <S2000
91c0: 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58  0><S30200>.** EX
91d0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
91e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
91f0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9200: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
9210: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
9220: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
9230: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
9240: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
9250: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
9260: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
9270: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
9280: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
9290: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
92a0: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
92b0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
92c0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
92d0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
92e0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
92f0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
9300: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
9310: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
9320: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
9330: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
9340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9350: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
9360: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
9370: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9380: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
9390: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
93a0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
93b0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
93c0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
93d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
93e0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
93f0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
9400: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
9410: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
9420: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
9430: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
9440: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
9450: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9460: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
9470: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
9480: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
9490: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
94a0: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63  , that sqlite3_c
94b0: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
94c0: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
94d0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
94e0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
94f0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
9500: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
9510: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
9520: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
9530: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
9540: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
9550: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
9560: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
9570: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
9580: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
9590: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
95a0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
95b0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
95c0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
95d0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
95e0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
95f0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
9600: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
9610: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
9620: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
9630: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
9640: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
9650: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
9660: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
9670: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9680: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
9690: 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f  OK]..** If the o
96a0: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
96b0: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
96c0: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
96d0: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
96e0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
96f0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
9700: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
9710: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
9720: 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31  .** [H14103] [H1
9730: 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b  4106] [H14120] [
9740: 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d  H14123] [H14126]
9750: 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33   [H14129] [H1413
9760: 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b  2] [H14135].** [
9770: 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d  H14138] [H14141]
9780: 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34   [H14144] [H1414
9790: 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34  7] [H14150] [H14
97a0: 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48  153] [H14156] [H
97b0: 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36  14159].** [H1416
97c0: 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34  2] [H14165] [H14
97d0: 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  168].*/.SQLITE_E
97e0: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
97f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
9800: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
9810: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
9820: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
9830: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
9840: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
9850: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
9860: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
9870: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
9880: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
9890: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
98a0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
98b0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
98c0: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
98d0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
98e0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
98f0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
9900: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
9910: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
9920: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
9930: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
9940: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
9950: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
9960: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
9970: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
9980: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
9990: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
99a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
99b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
99c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
99d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
99e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
99f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
9a00: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
9a10: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
9a20: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
9a30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
9a40: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
9a50: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
9a60: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
9a70: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
9a80: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
9a90: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
9aa0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
9ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
9ac0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
9ad0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
9ae0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
9af0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
9b00: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
9b10: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
9b20: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
9b30: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
9b40: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
9b50: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
9b60: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
9b70: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
9b80: 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  b..**.** Require
9b90: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30  ments:.** [H1420
9ba0: 33 5d 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34  3] [H14206] [H14
9bb0: 32 30 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48  209] [H14212] [H
9bc0: 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45  14215].*/.SQLITE
9bd0: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
9be0: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
9bf0: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
9c00: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
9c10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
9c20: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
9c30: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d  outines {H10155}
9c40: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50   <S20120>.** EXP
9c50: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
9c60: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
9c70: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
9c80: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
9c90: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
9ca0: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
9cb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
9cc0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
9cd0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
9ce0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
9cf0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
9d00: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9d10: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
9d20: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
9d30: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
9d40: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
9d50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
9d60: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
9d70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
9d80: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
9d90: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
9da0: 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  .  By creating a
9db0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
9dc0: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
9dd0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
9de0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9df0: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  ] during configu
9e00: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70  ration, an.** ap
9e10: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
9e20: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
9e30: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tive memory allo
9e40: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
9e50: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74  .** for SQLite t
9e60: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
9e70: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
9e80: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
9e90: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
9ea0: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62  e comes with a b
9eb0: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
9ec0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73  llocator that is
9ed0: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64  .** perfectly ad
9ee0: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
9ef0: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
9f00: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
9f10: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
9f20: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
9f30: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
9f40: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
9f50: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
9f60: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
9f70: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
9f80: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
9f90: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
9fa0: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
9fb0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
9fc0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
9fd0: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
9fe0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
9ff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
a000: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
a010: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
a020: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
a030: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
a040: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
a050: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
a060: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
a070: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
a080: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
a090: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61   xFree, and xRea
a0a0: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73  lloc methods mus
a0b0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
a0c0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65  ** malloc(), fre
a0d0: 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63  e(), and realloc
a0e0: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
a0f0: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c  m the standard l
a100: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53  ibrary..**.** xS
a110: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
a120: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
a130: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
a140: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
a150: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
a160: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
a170: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
a180: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
a190: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
a1a0: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
a1b0: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
a1c0: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
a1d0: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
a1e0: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
a1f0: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
a200: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
a210: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
a220: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
a230: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
a240: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
a250: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
a260: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
a270: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
a280: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
a290: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
a2a0: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
a2b0: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
a2c0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
a2d0: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
a2e0: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
a2f0: 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68  r of 2..**.** Th
a300: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
a310: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
a320: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
a330: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
a340: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
a350: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
a360: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
a370: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
a380: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
a390: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
a3a0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
a3b0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
a3c0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
a3d0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
a3e0: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
a3f0: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
a400: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
a410: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
a420: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
a430: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
a440: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a450: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
a460: 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  down..*/.typedef
a470: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
a480: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
a490: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
a4a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a4b0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
a4c0: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
a4d0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
a4e0: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
a4f0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
a500: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
a510: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
a520: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
a530: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
a540: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
a550: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
a560: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
a570: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
a580: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
a590: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
a5a0: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
a5b0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
a5c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
a5d0: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
a5e0: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
a5f0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
a600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
a610: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
a620: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
a630: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
a640: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
a650: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
a660: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
a670: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
a680: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
a690: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
a6a0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
a6b0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
a6c0: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
a6d0: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
a6e0: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
a6f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a700: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
a710: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
a720: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
a730: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
a740: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
a750: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
a760: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
a770: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
a780: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
a790: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
a7a0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
a7b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
a7c0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
a7d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
a7e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
a7f0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
a800: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a810: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
a820: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
a830: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
a840: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
a850: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
a860: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
a870: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
a880: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
a890: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
a8a0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
a8b0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
a8c0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
a8d0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
a8e0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
a8f0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
a900: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
a910: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
a920: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
a930: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
a940: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
a950: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
a960: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
a970: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
a980: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
a990: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
a9a0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
a9b0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
a9c0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
a9d0: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
a9e0: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
a9f0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
aa00: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
aa10: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
aa20: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
aa30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
aa40: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
aa50: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
aa60: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
aa70: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
aa80: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
aa90: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
aaa0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
aab0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
aac0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aad0: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
aae0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
aaf0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
ab00: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
ab10: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
ab20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
ab30: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
ab40: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
ab50: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
ab60: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
ab70: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
ab80: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
ab90: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
aba0: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
abb0: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
abc0: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
abd0: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
abe0: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
abf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
ac00: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
ac10: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61    See the [threa
ac20: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f  ding mode].** do
ac30: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
ac40: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
ac50: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
ac60: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ac70: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
ac80: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
ac90: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
aca0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
acb0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
acc0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
acd0: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
ace0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
acf0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
ad00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ad10: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
ad20: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
ad30: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
ad40: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
ad50: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
ad60: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ad70: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
ad80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
ad90: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
ada0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
adb0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
adc0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
add0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
ade0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
adf0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
ae00: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
ae10: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
ae20: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
ae30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ae40: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
ae50: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ae60: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
ae70: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
ae80: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
ae90: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
aea0: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
aeb0: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
aec0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
aed0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
aee0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
aef0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
af00: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
af10: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
af20: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
af30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
af40: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
af50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
af60: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
af70: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
af80: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
af90: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
afa0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
afb0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
afc0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
afd0: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
afe0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
aff0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
b000: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
b010: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
b020: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
b030: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
b040: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
b050: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
b060: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
b070: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
b080: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
b090: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b0a0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
b0b0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
b0c0: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
b0d0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
b0e0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
b0f0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
b100: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b110: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
b120: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
b130: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
b140: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
b150: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
b160: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
b170: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
b180: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
b190: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
b1a0: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
b1b0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
b1c0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
b1d0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
b1e0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
b1f0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
b200: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
b210: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b220: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
b230: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
b240: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
b250: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
b260: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
b270: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
b280: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
b290: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64  atistics. When d
b2a0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
b2b0: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
b2c0: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
b2d0: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  .** non-operatio
b2e0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
b2f0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b300: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
b310: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
b320: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
b330: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
b340: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
b350: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
b360: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
b370: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
b380: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
b390: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b3a0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
b3b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
b3c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
b3d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
b3e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
b3f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
b400: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
b410: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
b420: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
b430: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
b440: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20   memory, the.** 
b450: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
b460: 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29  atch buffer (sz)
b470: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
b480: 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e   of buffers (N).
b490: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
b4a0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
b4b0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
b4c0: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
b4d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20  should be a few 
b4e0: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20  bytes.** larger 
b4f0: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20  than the actual 
b500: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65  scratch space re
b510: 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72  quired due inter
b520: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a  nal overhead..**
b530: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
b540: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
b550: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
b560: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
b570: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
b580: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
b590: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
b5a0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
b5b0: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
b5c0: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
b5d0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
b5e0: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
b5f0: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
b600: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
b610: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
b620: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
b630: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
b640: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
b650: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
b660: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
b670: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
b680: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
b690: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
b6a0: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
b6b0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
b6c0: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
b6d0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
b6e0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
b6f0: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
b700: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
b710: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
b720: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
b730: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
b740: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
b750: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
b760: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
b770: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
b780: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b790: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
b7a0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
b7b0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
b7c0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
b7d0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
b7e0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
b7f0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
b800: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
b810: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
b820: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
b830: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
b840: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
b850: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
b860: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
b870: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
b880: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
b890: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
b8a0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
b8b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
b8c0: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
b8d0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
b8e0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
b8f0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
b900: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f  r to the.** memo
b910: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
b920: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
b930: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
b940: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
b950: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
b960: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
b970: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
b980: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
b990: 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a  768.  The first.
b9a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b9b0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
b9c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
b9d0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
b9e0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
b9f0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
ba00: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
ba10: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
ba20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
ba30: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
ba40: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
ba50: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
ba60: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
ba70: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f  che.  If additio
ba80: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
ba90: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
baa0: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
bab0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
bac0: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
bad0: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
bae0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
baf0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
bb00: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
bb10: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d  space..** The im
bb20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
bb30: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
bb40: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
bb50: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
bb60: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
bb70: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c  g information. <
bb80: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bb90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
bba0: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
bbb0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
bbc0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
bbd0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
bbe0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
bbf0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
bc00: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
bc10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
bc20: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
bc30: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
bc40: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
bc50: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
bc60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
bc70: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
bc80: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
bc90: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
bca0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
bcb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
bcc0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
bcd0: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
bce0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
bcf0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49  ocation size.  I
bd00: 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  f.** the first p
bd10: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
bd20: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
bd30: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
bd40: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
bd50: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
bd60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bd70: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
bd80: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
bd90: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
bda0: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
bdb0: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
bdc0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
bdd0: 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65  ].  If the.** me
bde0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
bdf0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
be00: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
be10: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
be20: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
be30: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
be40: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
be50: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
be60: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
be70: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
be80: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
be90: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
bea0: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64  ation needs.</dd
beb0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
bec0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
bed0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bee0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bef0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bf00: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bf10: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
bf20: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
bf30: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
bf40: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
bf50: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
bf60: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
bf70: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
bf80: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
bf90: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
bfa0: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
bfb0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
bfc0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
bfd0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bfe0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
bff0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
c000: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c010: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c020: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c030: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c040: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c050: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c060: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c070: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
c080: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
c090: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
c0a0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c0b0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
c0c0: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
c0d0: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
c0e0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
c0f0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
c100: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
c110: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c120: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c130: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
c140: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
c150: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
c160: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
c170: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
c180: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c190: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
c1a0: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
c1b0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c1c0: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
c1d0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
c1e0: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
c1f0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74  ** memory allcat
c200: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70  ion lookaside op
c210: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65  timization.  The
c220: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c230: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
c240: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
c250: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
c260: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
c270: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
c280: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
c290: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
c2a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64   connection.</dd
c2b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c2c0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
c2d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c2e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
c2f0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c300: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
c310: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
c320: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
c330: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
c340: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
c350: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
c360: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
c370: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
c380: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51  lementation.  SQ
c390: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
c3a0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
c3b0: 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
c3c0: 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
c3d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
c3e0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c3f0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
c400: 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  ETPCACHE</dt>.**
c410: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c420: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c430: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c440: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c450: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
c460: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
c470: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
c480: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
c490: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
c4a0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c4b0: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
c4c0: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  t.</dd>.**.** </
c4d0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
c4e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
c4f0: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
c500: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
c510: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c520: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
c530: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
c540: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
c550: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
c560: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c570: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c580: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
c590: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
c5a0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c5c0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
c5d0: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
c5e0: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
c5f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c600: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
c610: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
c620: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
c630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c640: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
c650: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
c660: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
c670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c680: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
c690: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
c6a0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
c6b0: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
c6c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
c6d0: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
c6e0: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
c6f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c700: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
c710: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
c720: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
c730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c740: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
c750: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
c760: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
c770: 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
c780: 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
c790: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
c7a0: 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
c7b0: 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
c7c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
c7d0: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
c7e0: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
c7f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c800: 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
c810: 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
c820: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
c830: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c840: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
c850: 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
c860: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
c870: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ods* */../*.** C
c880: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
c890: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
c8a0: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e  H10170} <S20000>
c8b0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
c8c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
c8d0: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
c8e0: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
c8f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c900: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
c910: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
c920: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
c930: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
c940: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
c950: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
c960: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
c970: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
c980: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c990: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c9a0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
c9b0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c9c0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
c9d0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
c9e0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
c9f0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
ca00: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
ca10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
ca20: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
ca30: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
ca40: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
ca50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
ca60: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ca70: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ca80: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ca90: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
caa0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
cab0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
cac0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cad0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
cae0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
caf0: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
cb00: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
cb10: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
cb20: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
cb30: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
cb40: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
cb50: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
cb60: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
cb70: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
cb80: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
cb90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cba0: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
cbb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
cbc0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
cbd0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
cbe0: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
cbf0: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
cc00: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
cc10: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
cc20: 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66  e memory.  The f
cc30: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
cc40: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
cc50: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
cc60: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
cc70: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
cc80: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
cc90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
cca0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65  lloc()].  The se
ccb0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
ccc0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
ccd0: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
cce0: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
ccf0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
cd00: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
cd10: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
cd20: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
cd30: 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
cd40: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
cd50: 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
cd60: 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
cd70: 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
cd80: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
cd90: 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64  rd arguments.</d
cda0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
cdb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cdc0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
cdd0: 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
cde0: 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
cdf0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ce00: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
ce10: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
ce20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32  sult Codes {H122
ce30: 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  00} <S10700>.**.
ce40: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
ce50: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
ce60: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
ce70: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
ce80: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
ce90: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
cea0: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
ceb0: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
cec0: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
ced0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
cee0: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
cef0: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
cf00: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
cf10: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  tions..**.** Req
cf20: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
cf30: 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a  12201] [H12202].
cf40: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
cf50: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
cf60: 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
cf70: 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
cf80: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
cf90: 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48   Insert Rowid {H
cfa0: 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a  12220} <S10700>.
cfb0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79  **.** Each entry
cfc0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
cfd0: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
cfe0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
cff0: 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
d000: 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
d010: 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20  | "rowid"]. The 
d020: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
d030: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
d040: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
d050: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
d060: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
d070: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
d080: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
d090: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
d0a0: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
d0b0: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
d0c0: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
d0d0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
d0e0: 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
d0f0: 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
d100: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
d110: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
d120: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
d130: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
d140: 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
d150: 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
d160: 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
d170: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
d180: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
d190: 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
d1a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
d1b0: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
d1c0: 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20  rgument.  If no 
d1d0: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
d1e0: 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
d1f0: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
d200: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
d210: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
d220: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
d230: 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
d240: 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
d250: 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65  rigger, then the
d260: 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
d270: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
d280: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
d290: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
d2a0: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
d2b0: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  er is running..*
d2c0: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
d2d0: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
d2e0: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
d2f0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
d300: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73  utine.** reverts
d310: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
d320: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
d330: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66  re the trigger f
d340: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  ired..**.** An [
d350: 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
d360: 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
d370: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
d380: 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
d390: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
d3a0: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
d3b0: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
d3c0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
d3d0: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
d3e0: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
d3f0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
d400: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
d410: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
d420: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
d430: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
d440: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
d450: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
d460: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
d470: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
d480: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
d490: 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
d4a0: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
d4b0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
d4c0: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
d4d0: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
d4e0: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
d4f0: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
d500: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
d510: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
d520: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
d530: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
d540: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
d550: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
d560: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
d570: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
d580: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
d590: 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
d5a0: 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
d5b0: 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
d5c0: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
d5d0: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
d5e0: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
d5f0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
d600: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
d610: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20  ts:.** [H12221] 
d620: 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12223].**.** I
d630: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
d640: 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
d650: 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
d660: 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
d670: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
d680: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
d690: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
d6a0: 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
d6b0: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
d6c0: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
d6d0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
d6e0: 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
d6f0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
d700: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
d710: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
d720: 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
d730: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
d740: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
d750: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
d760: 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
d770: 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
d780: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
d790: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
d7a0: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
d7b0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
d7c0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
d7d0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
d7e0: 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20  dified {H12240} 
d7f0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
d800: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
d810: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
d820: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
d830: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
d840: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
d850: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
d860: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
d870: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
d880: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
d890: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
d8a0: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
d8b0: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
d8c0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f   parameter..** O
d8d0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
d8e0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
d8f0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
d900: 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
d910: 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
d920: 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
d930: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
d940: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
d950: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
d960: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
d970: 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
d980: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d990: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  s()] function.**
d9a0: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
d9b0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
d9c0: 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63  nges including c
d9d0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
d9e0: 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   triggers..**.**
d9f0: 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20   A "row change" 
da00: 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
da10: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
da20: 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
da30: 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
da40: 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
da50: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
da60: 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
da70: 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
da80: 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
da90: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
daa0: 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
dab0: 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
dac0: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52  T processing, DR
dad0: 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20  OP TABLE, or by 
dae0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
daf0: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
db00: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
db10: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
db20: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
db30: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
db40: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
db50: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
db60: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
db70: 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67  cript of a trigg
db80: 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74  er.  Most SQL st
db90: 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
dba0: 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
dbb0: 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
dbc0: 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
dbd0: 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
dbe0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
dbf0: 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
dc00: 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
dc10: 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
dc20: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
dc30: 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
dc40: 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
dc50: 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
dc60: 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
dc70: 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
dc80: 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
dc90: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61  ration..**.** Ca
dca0: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
dcb0: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
dcc0: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
dcd0: 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
dce0: 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
dcf0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
dd00: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
dd10: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
dd20: 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
dd30: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
dd40: 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
dd50: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
dd60: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
dd70: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
dd80: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
dd90: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
dda0: 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c  * Thus, when cal
ddb0: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
ddc0: 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
ddd0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
dde0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
ddf0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
de00: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
de10: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
de20: 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
de30: 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
de40: 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74   top level.  Wit
de50: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
de60: 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
de70: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
de80: 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
de90: 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
dea0: 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
deb0: 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
dec0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
ded0: 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
dee0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
def0: 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
df00: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
df10: 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
df20: 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
df30: 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
df40: 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
df50: 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
df60: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
df70: 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
df80: 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
df90: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
dfa0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
dfb0: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
dfc0: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
dfd0: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
dfe0: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
dff0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
e000: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
e010: 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20  able.  Doing so 
e020: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
e030: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
e040: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
e050: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
e060: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
e070: 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f  able.  Because o
e080: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69  f this.** optimi
e090: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
e0a0: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45  tions in "DELETE
e0b0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
e0c0: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
e0d0: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74   and.** will not
e0e0: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74   be counted by t
e0f0: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
e100: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
e110: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
e120: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20  ].** functions, 
e130: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
e140: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
e150: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
e160: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20  riginally.** in 
e170: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67  the table.  To g
e180: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
e190: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
e1a0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
e1b0: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
e1c0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
e1d0: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20  ERE 1" instead. 
e1e0: 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73   Or recompile us
e1f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
e200: 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45  TE_OMIT_TRUNCATE
e210: 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63  _OPTIMIZATION] c
e220: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e230: 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  on to disable th
e240: 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  e.** optimizatio
e250: 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73  n on all queries
e260: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
e270: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31  ents:.** [H12241
e280: 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a  ] [H12243].**.**
e290: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
e2a0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
e2b0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
e2c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e2d0: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
e2e0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
e2f0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
e300: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
e310: 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
e320: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
e330: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
e340: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
e350: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
e360: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
e370: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
e380: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
e390: 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2260} <S10600>.*
e3a0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
e3b0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
e3c0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
e3d0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
e3e0: 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45  NSERT,.** UPDATE
e3f0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
e400: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
e410: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e420: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
e430: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69  ..** The count i
e440: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
e450: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69  ges from all tri
e460: 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20  gger contexts.  
e470: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
e480: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
e490: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
e4a0: 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
e4b0: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
e4c0: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
e4d0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e4e0: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52  rocessing, or DR
e4f0: 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73  OP table process
e500: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e  ing..** The chan
e510: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20  ges are counted 
e520: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73  as soon as the s
e530: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
e540: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63  kes them is.** c
e550: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
e560: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
e570: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
e580: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
e590: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
e5a0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
e5b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
e5c0: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
e5d0: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
e5e0: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20   table" without 
e5f0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a  a WHERE clause.*
e600: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  * by dropping an
e610: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
e620: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
e630: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
e640: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
e650: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
e660: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
e670: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
e680: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
e690: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69  f this.** optimi
e6a0: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
e6b0: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45  tions in "DELETE
e6c0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
e6d0: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
e6e0: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74   and.** will not
e6f0: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74   be counted by t
e700: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
e710: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
e720: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
e730: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20  ].** functions, 
e740: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
e750: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
e760: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
e770: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20  riginally.** in 
e780: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67  the table.  To g
e790: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
e7a0: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
e7b0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
e7c0: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
e7d0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
e7e0: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20  ERE 1" instead. 
e7f0: 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75    Or recompile u
e800: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
e810: 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54  ITE_OMIT_TRUNCAT
e820: 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20  E_OPTIMIZATION] 
e830: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e840: 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ion to disable t
e850: 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  he.** optimizati
e860: 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65  on on all querie
e870: 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
e880: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
e890: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
e8a0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ace..**.** Requi
e8b0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
e8c0: 32 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a  261] [H12263].**
e8d0: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
e8e0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
e8f0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
e900: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
e910: 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
e920: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e930: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
e940: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
e950: 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
e960: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
e970: 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
e980: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
e990: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
e9a0: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
e9b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
e9c0: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
e9d0: 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31  unning Query {H1
e9e0: 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a  2270} <S30500>.*
e9f0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
ea00: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
ea10: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
ea20: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
ea30: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
ea40: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
ea50: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
ea60: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
ea70: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
ea80: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
ea90: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
eaa0: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
eab0: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
eac0: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
ead0: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
eae0: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
eaf0: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
eb00: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
eb10: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
eb20: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
eb30: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
eb40: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
eb50: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
eb60: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
eb70: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
eb80: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
eb90: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
eba0: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
ebb0: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
ebc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ebd0: 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
ebe0: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
ebf0: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
ec00: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ec10: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
ec20: 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
ec30: 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
ec40: 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
ec50: 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
ec60: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ec70: 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
ec80: 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
ec90: 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
eca0: 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
ecb0: 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
ecc0: 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
ecd0: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
ece0: 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
ecf0: 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
ed00: 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
ed10: 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
ed20: 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  RUPT]..** If the
ed30: 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
ed40: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
ed50: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
ed60: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
ed70: 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
ed80: 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
ed90: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
eda0: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
edb0: 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
edc0: 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
edd0: 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  ically..**.** A 
ede0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
edf0: 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
ee00: 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
ee10: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
ee20: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
ee30: 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
ee40: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
ee50: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
ee60: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37  ments:.** [H1227
ee70: 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a  1] [H12272].**.*
ee80: 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
ee90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
eea0: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
eeb0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
eec0: 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
eed0: 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
eee0: 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
eef0: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
ef00: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
ef10: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
ef20: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
ef30: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
ef40: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
ef50: 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32  e {H10510} <S702
ef60: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
ef70: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
ef80: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
ef90: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
efa0: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
efb0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
efc0: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
efd0: 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
efe0: 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
eff0: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
f000: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
f010: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
f020: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
f030: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
f040: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
f050: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
f060: 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
f070: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
f080: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
f090: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
f0a0: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
f0b0: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
f0c0: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
f0d0: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
f0e0: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
f0f0: 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
f100: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
f110: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
f120: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
f130: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
f140: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
f150: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
f160: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
f170: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
f180: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
f190: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
f1a0: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
f1b0: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
f1c0: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
f1d0: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
f1e0: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
f1f0: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
f200: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
f210: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
f220: 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
f230: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
f240: 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
f250: 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
f260: 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
f270: 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 52  ect SQL..**.** R
f280: 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
f290: 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a  0511] [H10512].*
f2a0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
f2b0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
f2c0: 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
f2d0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
f2e0: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
f2f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
f300: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
f310: 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
f320: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
f330: 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
f340: 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
f350: 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
f360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
f370: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
f380: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
f390: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
f3a0: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
f3b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f3c0: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
f3d0: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
f3e0: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
f3f0: 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
f400: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
f410: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
f420: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
f430: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
f440: 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
f450: 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
f460: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
f470: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
f480: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
f490: 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
f4a0: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
f4b0: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
f4c0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
f4d0: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
f4e0: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
f4f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
f500: 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
f510: 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
f520: 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
f530: 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
f540: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
f550: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
f560: 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
f570: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
f580: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
f590: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
f5a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
f5b0: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
f5c0: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
f5d0: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
f5e0: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
f5f0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
f600: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
f610: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f620: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
f630: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
f640: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
f650: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
f660: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
f670: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
f680: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
f690: 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
f6a0: 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
f6b0: 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
f6c0: 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
f6d0: 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
f6e0: 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
f6f0: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
f700: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
f710: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
f720: 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
f730: 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
f740: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
f750: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
f760: 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
f770: 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
f780: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
f790: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
f7a0: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
f7b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
f7c0: 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
f7d0: 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
f7e0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
f7f0: 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
f800: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
f810: 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
f820: 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
f830: 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
f840: 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
f850: 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
f860: 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
f870: 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
f880: 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
f890: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
f8a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
f8b0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
f8c0: 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
f8d0: 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
f8e0: 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
f8f0: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
f900: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
f910: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
f920: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
f930: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
f940: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
f950: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
f960: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
f970: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
f980: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
f990: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
f9a0: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
f9b0: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
f9c0: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
f9d0: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
f9e0: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
f9f0: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
fa00: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
fa10: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
fa20: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
fa30: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
fa40: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
fa50: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
fa60: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
fa70: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
fa80: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
fa90: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
faa0: 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
fab0: 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
fac0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
fad0: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
fae0: 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
faf0: 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
fb00: 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
fb10: 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
fb20: 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
fb30: 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
fb40: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
fb50: 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
fb60: 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
fb70: 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
fb80: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
fb90: 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
fba0: 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
fbb0: 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
fbc0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
fbd0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
fbe0: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
fbf0: 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
fc00: 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
fc10: 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
fc20: 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
fc30: 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
fc40: 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
fc50: 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
fc60: 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
fc70: 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
fc80: 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
fc90: 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
fca0: 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
fcb0: 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
fcc0: 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
fcd0: 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
fce0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
fcf0: 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
fd00: 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
fd10: 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
fd20: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fd30: 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
fd40: 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
fd50: 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
fd60: 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
fd70: 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
fd80: 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
fd90: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
fda0: 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
fdb0: 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
fdc0: 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
fdd0: 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
fde0: 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
fdf0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
fe00: 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
fe10: 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
fe20: 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
fe30: 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
fe40: 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
fe50: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
fe60: 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
fe70: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
fe80: 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
fe90: 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
fea0: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
feb0: 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
fec0: 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
fed0: 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
fee0: 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
fef0: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
ff00: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
ff10: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
ff20: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
ff30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ff40: 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
ff50: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
ff60: 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
ff70: 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
ff80: 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
ff90: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
ffa0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
ffb0: 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
ffc0: 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
ffd0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
ffe0: 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
fff0: 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
10000 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
10010 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
10020 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
10030 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
10040 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
10050 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
10060 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
10070 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
10080 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
10090 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
100a0 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31  .** [H12311] [H1
100b0 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b  2312] [H12314] [
100c0 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d  H12316] [H12318]
100d0 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  .**.** A busy ha
100e0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
100f0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
10100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
10110 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
10120 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
10130 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
10140 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
10150 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10160 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
10170 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
10180 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
10190 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
101a0 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32  usy Timeout {H12
101b0 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  340} <S40410>.**
101c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
101d0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
101e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
101f0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
10200 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
10210 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
10220 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
10230 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
10240 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
10250 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
10260 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
10270 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
10280 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
10290 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
102a0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
102b0 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22  {H12343} After "
102c0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
102d0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
102e0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
102f0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
10300 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
10310 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
10320 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
10330 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
10340 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
10350 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
10360 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
10370 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
10380 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
10390 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
103a0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
103b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
103c0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
103d0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
103e0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
103f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10400 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
10410 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
10420 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
10430 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
10440 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
10450 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10460 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
10470 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
10480 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
10490 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
104a0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
104b0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
104c0 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20  ts:.** [H12341] 
104d0 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34  [H12343] [H12344
104e0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
104f0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
10500 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
10510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10520 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
10530 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
10540 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33  ng Queries {H123
10550 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  70} <S10000>.**.
10560 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
10570 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
10580 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
10590 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
105a0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
105b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
105c0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
105d0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
105e0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
105f0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
10600 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
10610 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
10620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
10630 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
10640 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
10650 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
10660 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
10670 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
10680 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
10690 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
106a0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
106b0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
106c0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
106d0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
106e0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
106f0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10700 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
10710 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
10720 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
10730 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
10740 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
10750 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
10760 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
10770 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
10780 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
10790 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
107a0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
107b0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
107c0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
107d0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
107e0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
107f0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
10800 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
10810 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
10820 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
10830 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
10840 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
10850 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
10860 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
10870 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
10880 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
10890 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
108a0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
108b0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
108c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
108d0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
108e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
108f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
10900 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
10910 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
10920 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
10930 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
10940 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
10950 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
10960 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
10970 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
10980 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
10990 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
109a0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
109b0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
109c0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
109d0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
109e0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
109f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
10a00 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
10a10 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
10a20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
10a30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
10a40 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
10a50 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
10a60 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
10a70 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
10a80 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
10a90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
10aa0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
10ab0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
10ac0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
10ad0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
10ae0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
10af0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
10b00 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
10b10 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
10b20 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
10b30 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
10b40 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
10b50 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
10b60 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
10b70 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
10b80 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
10b90 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
10ba0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
10bb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
10bc0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
10bd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
10be0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
10bf0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
10c00 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
10c10 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
10c20 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
10c30 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
10c40 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
10c50 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
10c60 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
10c70 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
10c80 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10c90 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
10ca0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
10cb0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
10cc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10cd0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
10ce0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
10cf0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
10d00 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
10d10 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
10d20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10d30 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
10d40 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
10d50 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
10d60 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
10d70 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
10d80 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
10d90 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
10da0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
10db0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
10dc0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
10dd0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
10de0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73  t should.** pass
10df0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
10e00 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
10e10 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
10e20 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
10e30 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
10e40 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
10e50 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
10e60 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
10e70 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
10e80 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
10e90 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
10ea0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
10eb0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
10ec0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
10ed0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
10ee0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
10ef0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
10f00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
10f10 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
10f20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
10f30 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
10f40 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
10f50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
10f60 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
10f70 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
10f80 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
10f90 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
10fa0 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
10fb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
10fc0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
10fd0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
10fe0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
10ff0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
11000 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
11010 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
11020 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
11030 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
11040 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
11050 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
11060 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
11070 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
11080 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
11090 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
110a0 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
110b0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
110c0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
110d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
110e0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
110f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
11100 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
11110 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
11120 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48  371] [H12373] [H
11130 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20  12374] [H12376] 
11140 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32  [H12379] [H12382
11150 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
11160 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
11170 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
11180 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
11190 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
111a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
111b0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
111c0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
111d0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
111e0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
111f0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
11200 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
11210 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
11220 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
11230 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
11240 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
11250 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
11260 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
11270 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
11280 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
11290 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
112a0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
112b0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
112c0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
112d0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
112e0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
112f0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
11300 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
11310 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
11320 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
11330 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
11340 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
11350 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
11360 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
11370 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
11380 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
11390 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
113a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
113b0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
113c0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
113d0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
113e0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
113f0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
11400 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
11410 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
11420 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
11430 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
11440 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
11450 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
11460 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
11470 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
11480 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
11490 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
114a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
114b0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
114c0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
114d0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
114e0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
114f0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
11500 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
11510 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
11520 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
11530 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
11540 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
11550 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
11560 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
11570 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
11580 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
11590 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
115a0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
115b0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
115c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
115d0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
115e0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
115f0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
11600 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
11610 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
11620 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
11630 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
11640 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
11650 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
11660 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
11670 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
11680 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
11690 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
116a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
116b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
116c0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
116d0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
116e0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
116f0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
11700 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
11710 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
11720 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
11730 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
11740 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
11750 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
11760 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
11770 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
11780 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
11790 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
117a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
117b0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
117c0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
117d0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
117e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
117f0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
11800 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
11810 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11820 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
11830 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
11840 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
11850 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
11860 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
11870 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
11880 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
11890 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
118a0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
118b0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
118c0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
118d0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
118e0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
118f0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
11900 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
11910 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
11920 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
11930 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
11940 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
11950 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
11960 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
11970 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
11980 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
11990 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
119a0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
119b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
119c0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
119d0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
119e0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
119f0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
11a00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
11a10 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
11a20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
11a30 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
11a40 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
11a50 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
11a60 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
11a70 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
11a80 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
11a90 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
11aa0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
11ab0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
11ac0 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
11ad0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
11ae0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
11af0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
11b00 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
11b10 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
11b20 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
11b30 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
11b40 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
11b50 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
11b60 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
11b70 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
11b80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
11b90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11ba0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
11bb0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
11bc0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
11bd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
11be0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
11bf0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
11c00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
11c10 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
11c20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
11c30 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
11c40 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
11c50 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
11c60 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
11c70 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
11c80 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
11c90 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
11ca0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
11cb0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
11cc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
11cd0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
11ce0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
11cf0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
11d00 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
11d10 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
11d20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
11d30 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
11d40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
11d50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11d60 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
11d70 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
11d80 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
11d90 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
11da0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11db0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
11dc0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
11dd0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
11de0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
11df0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
11e00 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
11e10 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
11e20 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
11e30 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
11e40 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
11e50 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
11e60 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
11e70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
11e80 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
11e90 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
11ea0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
11eb0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
11ec0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
11ed0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
11ee0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
11ef0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
11f00 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
11f10 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
11f20 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
11f30 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
11f40 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
11f50 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
11f60 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
11f70 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
11f80 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
11f90 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
11fa0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
11fb0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
11fc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
11fd0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
11fe0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
11ff0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
12000 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
12010 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
12020 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
12030 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
12040 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
12050 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12060 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
12070 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
12080 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12090 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
120a0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
120b0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
120c0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
120d0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
120e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
120f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12100 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
12110 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
12120 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
12130 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
12140 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
12150 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
12160 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
12170 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
12180 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
12190 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
121a0 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
121b0 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
121c0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
121d0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
121e0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
121f0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
12200 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
12210 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
12220 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
12230 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
12240 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
12250 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20  ts:.** [H17403] 
12260 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37  [H17406] [H17407
12270 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ].*/.char *sqlit
12280 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
12290 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
122a0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
122b0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
122c0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
122d0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
122e0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
122f0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
12300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12310 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
12320 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37  n Subsystem {H17
12330 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  300} <S20000>.**
12340 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
12350 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20  ore  uses these 
12360 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
12370 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
12380 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
12390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
123a0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
123b0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
123c0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
123d0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
123e0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
123f0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
12400 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
12410 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
12420 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
12430 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
12440 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
12450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12460 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
12470 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
12480 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
12490 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
124a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
124b0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
124c0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
124d0 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
124e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
124f0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
12500 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
12510 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
12520 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
12530 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
12540 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
12550 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12560 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
12570 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
12580 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
12590 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
125a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
125b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
125c0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
125d0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
125e0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
125f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
12600 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12610 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
12620 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
12630 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
12640 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
12650 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
12660 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
12670 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
12680 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
12690 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
126a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
126b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
126c0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
126d0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
126e0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
126f0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
12700 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
12710 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
12720 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
12730 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
12740 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
12750 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
12760 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
12770 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
12780 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
12790 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
127a0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
127b0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
127c0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
127d0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
127e0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
127f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
12800 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
12810 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
12820 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
12830 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
12840 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12850 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
12860 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
12870 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
12880 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
12890 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
128a0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
128b0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
128c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
128d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
128e0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
128f0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
12900 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
12910 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
12920 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
12930 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
12940 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
12950 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
12960 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
12970 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
12980 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
12990 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
129a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
129b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
129c0 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
129d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
129e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
129f0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
12a00 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
12a10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
12a20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
12a30 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
12a40 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
12a50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
12a60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12a70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
12a80 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
12a90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
12aa0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12ab0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12ac0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
12ad0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
12ae0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
12af0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
12b00 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
12b10 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
12b20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
12b30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
12b40 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
12b50 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
12b60 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
12b70 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
12b80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
12b90 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
12ba0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
12bb0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
12bc0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
12bd0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
12be0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12bf0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
12c00 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
12c10 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
12c20 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
12c30 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
12c40 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
12c50 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
12c60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
12c70 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
12c80 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
12c90 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
12ca0 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
12cb0 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
12cc0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
12cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12ce0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
12cf0 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
12d00 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
12d10 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
12d20 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
12d30 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
12d40 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  H17382} However,
12d50 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
12d60 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
12d70 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
12d80 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
12d90 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
12da0 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
12db0 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
12dc0 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
12dd0 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
12de0 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
12df0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
12e00 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
12e10 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
12e20 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
12e30 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
12e40 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12e50 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
12e60 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
12e70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
12e80 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
12e90 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12ea0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
12eb0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
12ec0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
12ed0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
12ee0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
12ef0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
12f00 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
12f10 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
12f20 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
12f30 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
12f40 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
12f50 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
12f60 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
12f70 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
12f80 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
12f90 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
12fa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
12fb0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
12fc0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
12fd0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
12fe0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
12ff0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13000 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
13010 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
13020 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
13030 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
13040 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
13050 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
13060 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
13070 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
13080 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
13090 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
130a0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
130b0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
130c0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
130d0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
130e0 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
130f0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
13100 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
13110 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
13120 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
13130 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
13140 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
13150 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37  ** [H17303] [H17
13160 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48  304] [H17305] [H
13170 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20  17306] [H17310] 
13180 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35  [H17312] [H17315
13190 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48  ] [H17318].** [H
131a0 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20  17321] [H17322] 
131b0 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54  [H17323].**.** T
131c0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
131d0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
131e0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
131f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
13200 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
13210 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
13220 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
13230 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
13240 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
13250 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13260 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
13270 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
13280 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
13290 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
132a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
132b0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
132c0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
132d0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
132e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
132f0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
13300 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
13310 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13320 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
13330 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
13340 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
13350 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
13360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
13370 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
13380 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
13390 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
133a0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
133b0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
133c0 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
133d0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
133e0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
133f0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
13400 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
13410 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
13420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
13430 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
13440 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
13450 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13460 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
13470 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
13480 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
13490 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
134a0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  em..**.** Requir
134b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33  ements:.** [H173
134c0 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31  71] [H17373] [H1
134d0 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a  7374] [H17375].*
134e0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
134f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
13500 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
13510 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
13520 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13530 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
13540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13550 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
13560 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
13570 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
13580 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
13590 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
135a0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
135b0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
135c0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
135d0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
135e0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
135f0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
13600 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
13610 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
13620 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
13630 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
13640 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
13650 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
13660 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
13670 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
13680 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
13690 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
136a0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
136b0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
136c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
136d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
136e0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
136f0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
13700 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
13710 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
13720 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
13730 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
13740 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
13750 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
13760 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
13770 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
13780 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
13790 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
137a0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
137b0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
137c0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
137d0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
137e0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
137f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
13800 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
13810 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
13820 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
13830 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
13840 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
13850 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
13860 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
13870 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
13880 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
13890 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
138a0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
138b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39  ments:.** [H1739
138c0 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  2].*/.void sqlit
138d0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
138e0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
138f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13900 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
13910 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
13920 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53  acks {H12500} <S
13930 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70100>.**.** Thi
13940 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
13950 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
13960 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
13970 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
13980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13990 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
139a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
139b0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
139c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
139d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
139e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
139f0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
13a00 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
13a10 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
13a20 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
13a30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
13a40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
13a50 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
13a60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13a70 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
13a80 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
13a90 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
13aa0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
13ab0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
13ac0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
13ad0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
13ae0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
13af0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13b00 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
13b10 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
13b20 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
13b30 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
13b40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
13b50 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
13b60 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
13b70 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
13b80 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
13b90 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
13ba0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
13bb0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
13bc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
13bd0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
13be0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
13bf0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
13c00 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
13c10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13c20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
13c30 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
13c40 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
13c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
13c60 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
13c70 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
13c80 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
13c90 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
13ca0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
13cb0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
13cc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
13cd0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
13ce0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
13cf0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
13d00 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
13d10 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
13d20 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
13d30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
13d40 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
13d50 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
13d60 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
13d70 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57  uested is ok.  W
13d80 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
13d90 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
13da0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
13db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
13dc0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
13dd0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
13de0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
13df0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
13e00 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
13e10 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
13e20 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
13e30 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20  ess is denied.  
13e40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
13e50 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  r code is [SQLIT
13e60 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
13e70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
13e80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
13e90 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
13ea0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13eb0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
13ec0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
13ed0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
13ee0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
13ef0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
13f00 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
13f10 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
13f20 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
13f30 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
13f40 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
13f50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
13f60 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
13f70 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
13f80 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
13f90 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
13fa0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
13fb0 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  a table..**.** T
13fc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13fd0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
13fe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
13ff0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
14000 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
14010 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
14020 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
14030 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65  ) interface. The
14040 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14050 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
14060 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
14070 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
14080 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
14090 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
140a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
140b0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
140c0 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69  horized. The thi
140d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
140e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
140f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
14100 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
14110 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14120 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
14130 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
14140 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
14150 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
14160 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
14170 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
14180 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
14190 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
141a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
141b0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
141c0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
141d0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
141e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
141f0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
14200 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
14210 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
14220 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
14230 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
14240 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
14250 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
14260 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
14270 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
14280 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
14290 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
142a0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
142b0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
142c0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
142d0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
142e0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
142f0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
14300 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
14310 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
14320 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
14330 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
14340 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
14350 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
14360 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
14370 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
14380 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
14390 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
143a0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
143b0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
143c0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
143d0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
143e0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
143f0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
14400 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
14410 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
14420 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
14430 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
14440 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
14450 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
14460 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
14470 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
14480 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
14490 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
144a0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
144b0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
144c0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
144d0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
144e0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
144f0 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
14500 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
14510 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
14520 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
14530 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
14540 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
14550 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
14560 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
14570 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
14580 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73  vious call.  Dis
14590 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
145a0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
145b0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
145c0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
145d0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
145e0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
145f0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
14600 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
14610 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
14620 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
14630 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
14640 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
14650 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
14660 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14670 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
14680 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14690 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
146a0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
146b0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
146c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
146d0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
146e0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
146f0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
14700 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b  ph..**.** When [
14710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14720 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
14730 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
14740 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
14750 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
14760 72 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  reprepared durin
14770 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
14780 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
14790 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
147a0 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
147b0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
147c0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
147d0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
147e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
147f0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
14800 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
14810 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
14820 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
14830 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14840 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
14850 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
14860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
14870 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
14880 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
14890 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
148a0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
148b0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
148c0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
148d0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  p()]..**.** Requ
148e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
148f0 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b  2501] [H12502] [
14900 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d  H12503] [H12504]
14910 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30   [H12505] [H1250
14920 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32  6] [H12507] [H12
14930 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d  510].** [H12511]
14940 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32   [H12512] [H1252
14950 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32  0] [H12521] [H12
14960 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  522].*/.int sqli
14970 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
14980 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
14990 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
149a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
149b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
149c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
149d0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
149e0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
149f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14a00 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
14a10 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
14a20 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
14a30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
14a40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
14a50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
14a60 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
14a70 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
14a80 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
14a90 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
14aa0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
14ab0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
14ac0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
14ad0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
14ae0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
14af0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
14b00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
14b10 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
14b20 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
14b30 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
14b40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
14b50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
14b60 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
14b70 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
14b80 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
14b90 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
14ba0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
14bb0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
14bc0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
14bd0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
14be0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
14bf0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
14c00 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
14c10 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
14c20 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
14c30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
14c40 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
14c50 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
14c60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14c70 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
14c80 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
14c90 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
14ca0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
14cb0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
14cc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14cd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
14ce0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
14cf0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
14d00 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
14d10 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
14d20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
14d30 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
14d40 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
14d50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14d60 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
14d70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
14d80 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
14d90 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
14da0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
14db0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
14dc0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
14dd0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
14de0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
14df0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
14e00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
14e10 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
14e20 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
14e30 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
14e40 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
14e50 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
14e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
14e70 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
14e80 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
14e90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14ea0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
14eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
14ec0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
14ed0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
14ee0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
14ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14f00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
14f10 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
14f20 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
14f30 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
14f40 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
14f50 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
14f60 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
14f70 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
14f80 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
14f90 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
14fa0 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
14fb0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
14fc0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
14fd0 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35   [H12551] [H1255
14fe0 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32  2] [H12553] [H12
14ff0 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  554].*/./*******
15000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15020 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
15030 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
15040 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
15050 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
15060 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
15070 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
15080 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
150a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
150b0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
150c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
150d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
150e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
150f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
15100 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
15110 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
15120 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15140 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
15150 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
15160 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15170 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15190 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
151a0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
151b0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
151c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
151d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
151e0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
151f0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
15200 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
15210 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15230 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
15240 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
15250 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
15260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15280 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
15290 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
152a0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
152b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
152c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
152d0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
152e0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
152f0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
15300 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
15320 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
15330 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
15340 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
15350 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15360 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15370 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
15380 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
15390 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
153a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
153b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
153c0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
153d0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
153e0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
153f0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
15400 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15410 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
15420 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
15430 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
15440 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
15450 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
15460 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
15470 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
15480 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
15490 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
154a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
154b0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
154c0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
154d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
154e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
154f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
15500 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
15510 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
15520 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15530 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15540 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
15550 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
15560 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
15570 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
15580 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15590 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
155a0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
155b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
155c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
155d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
155e0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
155f0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
15600 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
15610 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
15620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15630 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
15640 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
15650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15660 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
15670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15680 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
15690 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
156a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
156b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
156c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
156d0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
156e0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
156f0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
15700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15720 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
15730 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
15740 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
15750 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
15760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
15770 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
15780 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
15790 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
157a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
157b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
157c0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
157d0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
157e0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
157f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
15810 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
15820 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
15830 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
15840 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15850 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
15860 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
15870 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
15880 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
15890 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
158a0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
158b0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
158c0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
158d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
158e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
158f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
15900 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
15910 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
15920 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
15930 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
15940 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
15950 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
15960 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15970 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
15980 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
15990 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
159a0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
159b0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
159c0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
159d0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
159e0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
159f0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
15a00 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
15a10 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
15a20 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
15a30 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
15a40 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
15a50 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
15a60 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
15a70 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
15a80 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
15a90 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c  tions {H12280} <
15aa0 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60400>.** EXPER
15ab0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
15ac0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
15ad0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
15ae0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
15af0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
15b00 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
15b10 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
15b20 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
15b30 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
15b40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
15b50 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
15b60 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
15b70 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
15b80 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
15b90 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
15ba0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
15bb0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
15bc0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
15bd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15be0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
15bf0 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
15c00 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
15c10 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
15c20 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
15c30 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
15c40 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
15c50 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
15c60 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
15c70 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
15c80 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
15c90 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
15ca0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
15cb0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
15cc0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
15cd0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  trigger..**.** T
15ce0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
15cf0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
15d00 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
15d10 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
15d20 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
15d30 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
15d40 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
15d50 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
15d60 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
15d70 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
15d80 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
15d90 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
15da0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
15db0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
15dc0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
15dd0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
15de0 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b  s:.** [H12281] [
15df0 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d  H12282] [H12283]
15e00 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38   [H12284] [H1228
15e10 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32  5] [H12287] [H12
15e20 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a  288] [H12289].**
15e30 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c   [H12290].*/.SQL
15e40 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
15e50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
15e60 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
15e70 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
15e80 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
15e90 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
15ea0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
15eb0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
15ec0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
15ed0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
15ee0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
15ef0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
15f00 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15f10 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
15f20 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
15f30 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53  acks {H12910} <S
15f40 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60400>.**.** Thi
15f50 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
15f60 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
15f70 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
15f80 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
15f90 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
15fa0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
15fb0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
15fc0 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
15fd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
15fe0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
15ff0 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
16000 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16010 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
16020 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
16030 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
16040 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
16050 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
16060 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
16070 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
16080 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16090 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
160a0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
160b0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
160c0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
160d0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
160e0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
160f0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
16100 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
16110 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
16120 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
16130 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
16140 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
16150 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
16160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16170 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
16180 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
16190 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
161a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
161b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
161c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
161d0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
161e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
161f0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
16200 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
16210 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
16220 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  raph..**.** Requ
16230 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
16240 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b  2911] [H12912] [
16250 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d  H12913] [H12914]
16260 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31   [H12915] [H1291
16270 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32  6] [H12917] [H12
16280 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  918].**.*/.void 
16290 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
162a0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
162b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
162c0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
162d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
162e0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
162f0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
16300 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32  n {H12700} <S402
16310 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
16320 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
16330 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
16340 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
16350 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
16360 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
16370 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e  ument. The filen
16380 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
16390 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
163a0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
163b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
163c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
163d0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
163e0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
163f0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
16400 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
16410 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   A [database con
16420 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
16430 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
16440 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
16450 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
16460 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
16470 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
16480 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
16490 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
164a0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
164b0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
164c0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
164d0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
164e0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
164f0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
16500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
16510 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
16520 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62  ct. If the datab
16530 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
16540 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
16550 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
16560 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
16570 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
16580 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
16590 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
165a0 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  rned.  The.** [s
165b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
165c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
165d0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
165e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
165f0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
16600 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
16610 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
16620 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
16630 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
16640 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
16650 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
16660 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
16670 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
16680 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
16690 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
166a0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
166b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
166c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
166d0 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
166e0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
166f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
16700 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
16710 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
16720 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
16730 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16740 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
16750 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
16760 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
16770 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
16780 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
16790 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
167a0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
167b0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
167c0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
167d0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
167e0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
167f0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
16800 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
16810 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
16820 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
16830 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
16840 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
16850 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c  nection.  The fl
16860 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61  ags parameter ca
16870 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
16880 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
16890 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
168a0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
168b0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
168c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
168d0 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
168e0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
168f0 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  lags:.**.** <dl>
16900 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
16910 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
16920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
16930 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
16940 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
16950 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
16960 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
16970 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
16980 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
16990 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  urned.</dd>.**.*
169a0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
169b0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
169c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
169d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
169e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
169f0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
16a00 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
16a10 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
16a20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
16a30 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
16a40 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
16a50 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
16a60 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
16a70 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
16a80 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
16a90 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
16aa0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
16ab0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
16ac0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
16ad0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16ae0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
16af0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
16b00 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
16b10 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
16b20 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
16b30 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
16b40 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
16b50 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
16b60 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
16b70 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
16b80 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
16b90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
16ba0 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  n16().</dd>.** <
16bb0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
16bc0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
16bd0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
16be0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
16bf0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
16c00 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
16c10 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
16c20 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
16c30 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
16c40 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
16c50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
16c60 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  TEX] or [SQLITE_
16c70 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
16c80 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
16c90 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
16ca0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
16cb0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
16cc0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
16cd0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
16ce0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16cf0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
16d00 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
16d10 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
16d20 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
16d30 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
16d40 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
16d50 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
16d60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
16d70 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68  art-time.  If th
16d80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
16d90 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
16da0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
16db0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16dc0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
16dd0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
16de0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
16df0 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
16e00 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
16e10 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
16e20 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
16e30 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
16e40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
16e50 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
16e60 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
16e70 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
16e80 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
16e90 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
16ea0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
16eb0 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
16ec0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
16ed0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
16ee0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
16ef0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
16f00 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
16f10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
16f20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
16f30 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
16f40 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
16f50 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
16f60 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
16f70 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
16f80 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
16f90 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
16fa0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
16fb0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
16fc0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
16fd0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
16fe0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
16ff0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
17000 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
17010 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
17020 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
17030 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
17040 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
17050 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
17060 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
17070 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
17080 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
17090 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
170a0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
170b0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
170c0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
170d0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
170e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
170f0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
17100 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17110 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
17120 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
17130 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
17140 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
17150 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
17160 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
17170 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
17180 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
17190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
171a0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
171b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
171c0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
171d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
171e0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
171f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
17200 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
17210 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
17220 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
17230 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
17240 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
17250 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
17260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17270 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
17280 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
17290 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
172a0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
172b0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
172c0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
172d0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
172e0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
172f0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
17300 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
17310 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
17320 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
17330 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
17340 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
17350 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ()..**.** Requir
17360 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37  ements:.** [H127
17370 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31  01] [H12702] [H1
17380 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b  2703] [H12704] [
17390 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d  H12706] [H12707]
173a0 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31   [H12709] [H1271
173b0 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b  1].** [H12712] [
173c0 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d  H12713] [H12714]
173d0 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31   [H12717] [H1271
173e0 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32  9] [H12721] [H12
173f0 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  723].*/.int sqli
17400 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
17410 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
17420 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
17430 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
17440 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
17450 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
17460 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
17470 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
17480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
17490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
174a0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
174b0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
174c0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
174d0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
174e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
174f0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
17500 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
17510 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
17520 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
17530 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
17540 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
17550 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
17560 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
17570 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
17580 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
17590 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
175a0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
175b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
175c0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
175d0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
175e0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
175f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
17600 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
17610 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
17620 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
17630 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
17640 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
17650 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
17660 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
17670 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
17680 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
17690 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
176a0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
176b0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
176c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
176d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
176e0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
176f0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
17700 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
17710 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
17720 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
17730 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
17740 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
17750 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
17760 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69  fined.  The sqli
17770 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
17780 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
17790 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
177a0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
177b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
177c0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
177d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
177e0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
177f0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
17800 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
17810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17820 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
17830 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
17840 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
17850 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
17860 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
17870 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
17880 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
17890 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
178a0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
178b0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
178c0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
178d0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
178e0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
178f0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
17900 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
17910 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
17920 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
17930 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
17940 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
17950 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
17960 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
17970 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
17980 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
17990 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
179a0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ons..**.** When 
179b0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
179c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
179d0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
179e0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
179f0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
17a00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
17a10 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17a20 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
17a30 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
17a40 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
17a50 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
17a60 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
17a70 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
17a80 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
17a90 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
17aa0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
17ab0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
17ac0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
17ad0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
17ae0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
17af0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
17b00 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
17b10 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
17b20 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
17b30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
17b40 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
17b50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
17b60 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
17b70 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
17b80 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
17b90 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
17ba0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
17bb0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
17bc0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
17bd0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
17be0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
17bf0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
17c00 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
17c10 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
17c20 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
17c30 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
17c40 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
17c50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
17c60 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
17c70 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
17c80 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
17c90 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
17ca0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
17cb0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
17cc0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   not be set..**.
17cd0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
17ce0 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31  .** [H12801] [H1
17cf0 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b  2802] [H12803] [
17d00 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d  H12807] [H12808]
17d10 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74   [H12809].*/.int
17d20 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
17d30 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
17d40 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
17d50 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
17d60 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
17d70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
17d80 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
17d90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
17da0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
17db0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17dc0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
17dd0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
17de0 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a  13000} <H13010>.
17df0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
17e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17e10 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
17e20 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
17e30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
17e40 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
17e50 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
17e60 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
17e70 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
17e80 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
17e90 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
17ea0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
17eb0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
17ec0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
17ed0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
17ee0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
17ef0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
17f00 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
17f10 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
17f20 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
17f30 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
17f40 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
17f50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17f60 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
17f70 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
17f80 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
17f90 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
17fa0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
17fb0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
17fc0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
17fd0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
17fe0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
17ff0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
18000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
18010 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
18020 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
18030 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
18040 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
18050 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
18060 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
18070 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
18080 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
18090 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
180a0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
180b0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
180c0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
180d0 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
180e0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
180f0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
18100 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
18110 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
18120 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
18130 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
18140 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
18150 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
18160 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
18170 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20  Limits {H12760} 
18180 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20600>.**.** T
18190 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
181a0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
181b0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
181c0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
181d0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
181e0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
181f0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
18200 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
18210 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
18220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
18230 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
18240 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
18250 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
18260 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18270 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
18280 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
18290 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
182a0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
182b0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
182c0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
182d0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
182e0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
182f0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
18300 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f  ct.  The functio
18310 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c  n returns the ol
18320 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49  d limit..**.** I
18330 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
18340 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
18350 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
18360 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
18370 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63   For the limit c
18380 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54  ategory of SQLIT
18390 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72  E_LIMIT_XYZ ther
183a0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
183b0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
183c0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79  bound].** set by
183d0 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
183e0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
183f0 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b  acro named .** [
18400 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
18410 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68  MAX_XYZ]..** (Th
18420 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
18430 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
18440 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a  ed to "_MAX_".).
18450 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69  ** Attempts to i
18460 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
18470 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
18480 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
18490 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
184a0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
184b0 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a   upper limit..**
184c0 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
184d0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
184e0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
184f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
18500 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
18510 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
18520 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
18530 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
18540 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
18550 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
18560 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
18570 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
18580 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
18590 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
185a0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
185b0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
185c0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
185d0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
185e0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
185f0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
18600 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
18610 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
18620 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
18630 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
18640 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
18650 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
18660 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
18670 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
18680 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
18690 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
186a0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
186b0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
186c0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
186d0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
186e0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
186f0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
18700 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
18710 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
18720 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18730 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
18740 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
18750 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
18760 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
18770 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
18780 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
18790 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
187a0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
187b0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
187c0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
187d0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
187e0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
187f0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
18800 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
18810 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
18820 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
18830 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b  s:.** [H12762] [
18840 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d  H12766] [H12769]
18850 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18860 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
18870 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
18880 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
18890 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
188a0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
188b0 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
188c0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
188d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
188e0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
188f0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
18900 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
18910 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
18920 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
18930 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
18940 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
18950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
18960 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
18970 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
18980 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
18990 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
189a0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
189b0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
189c0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
189d0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
189e0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
189f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
18a00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18a10 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
18a20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18a30 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
18a40 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
18a50 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
18a60 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18a70 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
18a80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18a90 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
18aa0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
18ab0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
18ac0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18ad0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
18ae0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18af0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
18b00 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
18b10 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
18b20 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
18b30 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
18b40 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
18b50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
18b60 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
18b70 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
18b80 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
18b90 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  se.</dd>.**.** <
18ba0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18bb0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
18bc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18bd0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
18be0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
18bf0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
18c00 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18c10 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
18c20 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
18c30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
18c40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
18c50 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
18c60 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
18c70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18c80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
18c90 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
18ca0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18cb0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
18cc0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
18cd0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
18ce0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
18cf0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
18d00 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
18d10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18d20 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
18d30 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
18d40 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18d50 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
18d60 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
18d70 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18d80 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
18d90 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
18da0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18db0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
18dc0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
18dd0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
18de0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
18df0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
18e00 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
18e10 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
18e20 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
18e30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18e40 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
18e50 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
18e60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18e70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
18e80 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
18e90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18ea0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  mum number of va
18eb0 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51  riables in an SQ
18ec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
18ed0 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64   can.** be bound
18ee0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
18ef0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f00 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
18f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
18f30 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
18f40 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
18f50 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
18f60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
18f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18f80 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
18f90 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
18fa0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
18fb0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
18fc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
18fd0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
18fe0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
18ff0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
19000 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
19010 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
19020 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
19030 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
19040 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
19050 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
19060 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
19070 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
19080 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
19090 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
190a0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
190b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
190c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
190d0 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a             9../*
190e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
190f0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
19100 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30  tatement {H13010
19110 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45  } <S10000>.** KE
19120 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
19130 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
19140 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
19150 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
19160 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
19170 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
19180 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
19190 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
191a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
191b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
191c0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
191d0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
191e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
191f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
19200 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
19210 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
19220 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
19230 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19240 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
19250 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
19260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19270 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
19280 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
19290 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
192a0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
192b0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
192c0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
192d0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
192e0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
192f0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
19300 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
19310 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
19320 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
19330 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
19340 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
19350 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
19360 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
19370 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
19380 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
19390 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
193a0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
193b0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
193c0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
193d0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
193e0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
193f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
19400 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
19410 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
19420 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
19430 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
19440 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
19450 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
19460 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
19470 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
19480 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
19490 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
194a0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
194b0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
194c0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
194d0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
194e0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
194f0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
19500 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
19510 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
19520 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
19530 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
19540 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
19550 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
19560 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
19570 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
19580 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
19590 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
195a0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
195b0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
195c0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
195d0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
195e0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
195f0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
19600 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
19610 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
19620 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
19630 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
19640 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
19650 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
19660 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
19670 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
19680 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
19690 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
196a0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
196b0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
196c0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
196d0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
196e0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
196f0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
19700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19710 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
19720 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
19730 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
19740 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
19750 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
19760 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
19770 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
19780 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
19790 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
197a0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
197b0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
197c0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
197d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
197e0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
197f0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
19800 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
19810 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
19820 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
19830 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
19840 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
19850 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
19860 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
19870 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
19880 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
19890 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
198a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
198b0 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
198c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
198d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
198e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
198f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19900 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
19910 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
19920 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
19930 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
19940 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
19950 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
19960 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
19970 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
19980 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19990 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
199a0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
199b0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
199c0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
199d0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
199e0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
199f0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
19a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
19a10 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
19a20 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
19a30 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
19a40 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
19a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
19a60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
19a70 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
19a80 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
19a90 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
19aa0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
19ab0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
19ac0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
19ad0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
19ae0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
19af0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
19b00 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
19b10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
19b20 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
19b30 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
19b40 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
19b50 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
19b60 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
19b70 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
19b80 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
19b90 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
19ba0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
19bb0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
19bc0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
19bd0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
19be0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
19bf0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
19c00 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
19c10 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
19c20 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
19c30 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
19c40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
19c50 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
19c60 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
19c70 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
19c80 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
19c90 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
19ca0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
19cb0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
19cc0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
19cd0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
19ce0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
19cf0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
19d00 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
19d10 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
19d20 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
19d30 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
19d40 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
19d50 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
19d60 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
19d70 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
19d80 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
19d90 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
19da0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
19db0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
19dc0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
19dd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
19de0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
19df0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
19e00 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
19e10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19e20 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
19e30 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
19e40 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
19e50 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
19e60 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
19e70 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
19e80 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
19e90 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
19ea0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
19eb0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
19ec0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
19ed0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
19ee0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
19ef0 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d  H13011] [H13012]
19f00 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31   [H13013] [H1301
19f10 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33  4] [H13015] [H13
19f20 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48  016] [H13019] [H
19f30 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74  13021].**.*/.int
19f40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
19f50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
19f60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
19f70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
19f80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
19f90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
19fa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
19fb0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
19fc0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
19fd0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
19fe0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
19ff0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a000 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a010 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a020 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a030 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1a040 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1a050 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a060 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a070 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a080 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a090 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1a0a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a0b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1a0c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a0d0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1a0e0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1a0f0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1a100 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1a110 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a120 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1a130 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1a140 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a150 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a160 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a170 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a180 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1a190 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a1a0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a1b0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a1c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a1d0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1a1e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1a1f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1a200 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1a210 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1a220 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1a230 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1a240 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a250 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a260 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a270 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a280 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a290 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a2a0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a2b0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a2c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1a2d0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a2e0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a2f0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a300 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1a320 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1a330 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1a340 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1a350 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a360 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1a370 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1a380 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1a390 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1a3a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1a3b0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1a3c0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1a3d0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1a3e0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1a3f0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1a400 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1a410 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1a420 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1a430 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1a440 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1a450 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1a460 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1a470 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1a480 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e  H13100} <H13000>
1a490 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1a4a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1a4b0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1a4c0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1a4d0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1a4e0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1a4f0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1a500 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1a510 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1a520 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1a530 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1a540 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a550 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1a560 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1a570 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1a580 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20  ts:.** [H13101] 
1a590 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33  [H13102] [H13103
1a5a0 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1a5b0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
1a5c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1a5d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a5e0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
1a5f0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
1a600 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30  ct {H15000} <S20
1a610 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1a620 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1a630 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1a640 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a650 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1a660 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1a670 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a680 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1a690 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1a6a0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1a6b0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1a6c0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1a6d0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1a6e0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1a6f0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61  es it stores. Va
1a700 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1a710 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1a720 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
1a730 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
1a740 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
1a750 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
1a760 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
1a770 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1a780 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
1a790 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
1a7a0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
1a7b0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
1a7c0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
1a7d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1a7e0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
1a7f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
1a800 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
1a810 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
1a820 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
1a830 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1a840 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
1a850 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
1a860 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
1a870 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
1a880 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1a890 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1a8a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1a8b0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1a8c0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1a8d0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1a8e0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1a8f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1a900 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1a910 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1a920 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1a930 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1a940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1a950 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1a960 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1a970 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1a980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1a990 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1a9a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1a9b0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1a9c0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
1a9d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
1a9e0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
1a9f0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1aa00 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
1aa10 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
1aa20 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
1aa30 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
1aa40 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
1aa50 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1aa60 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
1aa70 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1aa80 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
1aa90 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
1aaa0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1aab0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1aac0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1aad0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
1aae0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
1aaf0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
1ab00 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
1ab10 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
1ab20 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1ab30 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1ab40 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
1ab50 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
1ab60 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
1ab70 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e   between between
1ab80 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1ab90 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1aba0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1abb0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
1abc0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
1abd0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1abe0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1abf0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1ac00 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1ac10 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1ac20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ac30 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1ac40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1ac50 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1ac60 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1ac70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1ac80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1ac90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1aca0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1acb0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1acc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1acd0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1ace0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1acf0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1ad00 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1ad10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1ad20 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1ad30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1ad40 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1ad50 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1ad60 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1ad70 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1ad80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ad90 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1ada0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1adb0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1adc0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1add0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1ade0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1adf0 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30   {H16001} <S2020
1ae00 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  0>.**.** The con
1ae10 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
1ae20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
1ae30 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
1ae40 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
1ae50 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
1ae60 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
1ae70 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1ae80 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1ae90 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1aea0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1aeb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1aec0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1aed0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1aee0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1aef0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1af00 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1af10 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1af20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1af30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1af40 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1af50 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1af60 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1af70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1af80 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1af90 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1afa0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1afb0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1afc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1afd0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1afe0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1aff0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1b000 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1b010 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1b020 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1b030 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1b040 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1b050 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
1b060 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30  {H13500} <S70300
1b070 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1b080 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1b090 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1b0a0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1b0b0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1b0c0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1b0d0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1b0e0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1b0f0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1b100 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1b110 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1b120 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b130 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
1b140 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
1b150 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
1b160 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
1b170 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] in one of thes
1b180 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1b190 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1b1a0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1b1b0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1b1c0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1b1d0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1b1e0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1b1f0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1b200 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1b210 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1b220 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69  al,.** and VVV i
1b230 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72  s an alpha-numer
1b240 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
1b250 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  e. The values of
1b260 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
1b270 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
1b280 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
1b290 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
1b2a0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
1b2b0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
1b2c0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1b2d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1b2e0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
1b2f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1b300 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1b310 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1b320 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1b330 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1b340 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1b350 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1b360 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1b370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b380 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1b390 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
1b3a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1b3b0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1b3c0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1b3d0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54   to be set..** T
1b3e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1b3f0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1b400 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1b410 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1b420 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1b430 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1b440 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1b450 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1b460 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1b470 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1b480 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1b490 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1b4a0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
1b4b0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
1b4c0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
1b4d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
1b4e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b4f0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
1b500 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
1b510 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
1b520 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
1b530 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
1b540 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
1b550 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1b560 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1b570 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
1b580 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
1b590 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
1b5a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
1b5b0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1b5c0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  999)..**.** The 
1b5d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
1b5e0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
1b5f0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
1b600 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
1b610 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
1b620 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
1b630 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
1b640 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1b650 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1b660 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
1b670 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
1b680 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
1b690 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
1b6a0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
1b6b0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
1b6c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1b6d0 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ters..** If the 
1b6e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1b6f0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
1b700 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
1b710 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
1b720 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1b730 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
1b740 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1b750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
1b760 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1b770 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1b780 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1b790 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1b7a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1b7b0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1b7c0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1b7d0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1b7e0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1b7f0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1b800 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1b810 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
1b820 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1b830 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1b840 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1b850 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1b860 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1b870 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1b880 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1b890 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1b8a0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1b8b0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
1b8c0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1b8d0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
1b8e0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1b8f0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
1b900 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
1b910 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
1b920 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
1b930 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
1b940 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1b950 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
1b960 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
1b970 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1b980 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1b990 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1b9a0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1b9b0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1b9c0 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f   zeroes.  A zero
1b9d0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1b9e0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1b9f0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1ba00 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1ba10 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
1ba20 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1ba30 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1ba40 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1ba50 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1ba60 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1ba70 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1ba80 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1ba90 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
1baa0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
1bab0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
1bac0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1bad0 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  s..** A negative
1bae0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1baf0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1bb00 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1bb10 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
1bb20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1bb30 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
1bb40 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
1bb50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1bb60 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
1bb70 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
1bb80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1bb90 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
1bba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bbb0 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
1bbc0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1bbd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1bbe0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1bbf0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
1bc00 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
1bc10 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
1bc20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1bc30 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1bc40 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
1bc50 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
1bc60 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
1bc70 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
1bc80 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
1bc90 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1bca0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
1bcb0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
1bcc0 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
1bcd0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
1bce0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
1bcf0 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  ls..** [SQLITE_M
1bd00 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20  ISUSE] might be 
1bd10 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
1bd20 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
1bd30 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69  alled on a.** vi
1bd40 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68  rtual machine th
1bd50 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
1bd60 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
1bd70 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
1bd80 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65  finalized..** De
1bd90 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73  tection of misus
1bda0 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e  e is unreliable.
1bdb0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73    Applications s
1bdc0 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64  hould not depend
1bdd0 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49  .** on SQLITE_MI
1bde0 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53  SUSE returns.  S
1bdf0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20  QLITE_MISUSE is 
1be00 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69  intended to indi
1be10 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69  cate a.** a logi
1be20 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61  c error in the a
1be30 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74  pplication.  Fut
1be40 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1be50 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1be60 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61  panic rather tha
1be70 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  n return SQLITE_
1be80 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65  MISUSE..**.** Se
1be90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1bea0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1beb0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
1bec0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1bed0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1bee0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1bef0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1bf00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1bf10 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35  ements:.** [H135
1bf20 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31  06] [H13509] [H1
1bf30 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b  3512] [H13515] [
1bf40 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d  H13518] [H13521]
1bf50 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32   [H13524] [H1352
1bf60 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b  7].** [H13530] [
1bf70 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d  H13533] [H13536]
1bf80 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34   [H13539] [H1354
1bf90 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33  2] [H13545] [H13
1bfa0 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a  548] [H13551].**
1bfb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1bfc0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1bfd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1bfe0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1bff0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1c000 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1c010 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1c020 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1c030 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1c040 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1c050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c060 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1c070 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1c080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c090 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1c0a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c0b0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1c0c0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1c0d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1c0e0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1c0f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1c100 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1c110 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1c120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c130 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1c140 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1c150 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1c160 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1c180 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1c190 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1c1a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1c1b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1c1c0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1c1d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1c1e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c1f0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1c200 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31  L Parameters {H1
1c210 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3600} <S70300>.*
1c220 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1c230 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1c240 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
1c250 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
1c260 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
1c270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c280 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
1c290 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
1c2a0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
1c2b0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
1c2c0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
1c2d0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
1c2e0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
1c2f0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
1c300 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
1c310 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
1c320 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
1c330 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
1c340 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  r time..**.** Th
1c350 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
1c360 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1c370 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
1c380 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
1c390 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
1c3a0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1c3b0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1c3c0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1c3d0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
1c3e0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
1c3f0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1c400 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1c410 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
1c420 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
1c430 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1c440 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1c450 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1c460 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1c470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1c480 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1c490 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c4a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c4b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1c4c0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1c4d0 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f  :.** [H13601].*/
1c4e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c4f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1c500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
1c510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c520 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
1c530 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33  t Parameter {H13
1c540 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  620} <S70300>.**
1c550 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c560 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c570 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
1c580 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
1c590 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
1c5a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1c5b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
1c5c0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1c5d0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
1c5e0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
1c5f0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
1c600 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
1c610 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
1c620 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
1c630 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
1c640 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
1c650 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
1c660 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
1c670 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
1c680 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
1c690 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
1c6a0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
1c6b0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
1c6c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
1c6d0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
1c6e0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
1c6f0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
1c700 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
1c710 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
1c720 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1c730 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
1c740 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
1c750 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
1c760 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
1c770 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
1c780 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
1c790 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
1c7a0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
1c7b0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
1c7c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
1c7d0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1c7e0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
1c7f0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
1c800 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
1c810 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
1c820 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
1c830 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
1c840 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
1c850 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
1c860 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1c870 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1c880 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1c890 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1c8a0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1c8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1c8c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1c8d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c8e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c8f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1c900 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1c910 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f  :.** [H13621].*/
1c920 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1c930 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c940 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
1c950 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
1c960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1c970 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
1c980 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
1c990 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c   Name {H13640} <
1c9a0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S70300>.**.** Re
1c9b0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
1c9c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1c9d0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
1c9e0 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78  e.  The.** index
1c9f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1ca00 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
1ca10 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
1ca20 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1ca30 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1ca40 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1ca50 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a  d()].  A zero.**
1ca60 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1ca70 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
1ca80 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
1ca90 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   The parameter.*
1caa0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
1cab0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
1cac0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
1cad0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
1cae0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
1caf0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
1cb00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1cb10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1cb20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1cb30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1cb40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1cb50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1cb60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1cb70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1cb80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1cb90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1cba0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1cbb0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a  ts:.** [H13641].
1cbc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1cbd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1cbe0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
1cbf0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
1cc00 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
1cc10 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
1cc20 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
1cc30 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1cc40 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
1cc50 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
1cc60 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
1cc70 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
1cc80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1cc90 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
1cca0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
1ccb0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
1ccc0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
1ccd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1cce0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
1ccf0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
1cd00 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
1cd10 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
1cd20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1cd30 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74   [H13661].*/.int
1cd40 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
1cd50 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
1cd60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1cd70 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
1cd80 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
1cd90 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
1cda0 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  10} <S10700>.**.
1cdb0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
1cdc0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1cdd0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1cde0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
1cdf0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1ce00 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
1ce10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1ce20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
1ce30 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1ce40 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
1ce50 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
1ce60 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
1ce70 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ATE])..**.** Req
1ce80 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1ce90 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13711].*/.int sq
1cea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
1ceb0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
1cec0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1ced0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
1cee0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
1cef0 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20  lt Set {H13720} 
1cf00 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1cf10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1cf20 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
1cf30 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
1cf40 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
1cf50 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
1cf60 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1cf70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
1cf80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1cf90 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
1cfa0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
1cfb0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1cfc0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1cfd0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
1cfe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1cff0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
1d000 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1d010 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1d020 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
1d030 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1d040 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
1d050 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d060 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
1d070 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
1d080 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
1d090 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d0a0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
1d0b0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
1d0c0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
1d0d0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
1d0e0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1d0f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
1d100 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
1d110 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
1d120 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
1d130 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
1d140 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1d150 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
1d160 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
1d170 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
1d180 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
1d190 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1d1a0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
1d1b0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
1d1c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d1d0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
1d1e0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
1d1f0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
1d200 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
1d210 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
1d220 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
1d230 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
1d240 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1d250 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1d260 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
1d270 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
1d280 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1d290 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
1d2a0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
1d2b0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
1d2c0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
1d2d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
1d2e0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
1d2f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
1d300 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
1d310 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
1d320 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
1d330 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
1d340 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
1d350 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1d360 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b  s:.** [H13721] [
1d370 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d  H13723] [H13724]
1d380 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32   [H13725] [H1372
1d390 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63  6] [H13727].*/.c
1d3a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1d3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
1d3c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d3d0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
1d3e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1d3f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1d400 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
1d410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d420 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
1d430 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
1d440 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
1d450 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1d460 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
1d470 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
1d480 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
1d490 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
1d4a0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
1d4b0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
1d4c0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1d4d0 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
1d4e0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
1d4f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
1d500 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
1d510 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
1d520 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
1d530 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
1d540 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
1d550 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
1d560 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
1d570 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
1d580 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
1d590 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
1d5a0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
1d5b0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
1d5c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
1d5d0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
1d5e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1d5f0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
1d600 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
1d610 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
1d620 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
1d630 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1d640 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
1d650 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1d660 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
1d670 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
1d680 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
1d690 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
1d6a0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
1d6b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
1d6c0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
1d6d0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
1d6e0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
1d6f0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
1d700 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1d710 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
1d720 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
1d730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1d740 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
1d750 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
1d760 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
1d770 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
1d780 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
1d790 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
1d7a0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1d7b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1d7c0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1d7d0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
1d7e0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
1d7f0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
1d800 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
1d810 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
1d820 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
1d830 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
1d840 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
1d850 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
1d860 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
1d870 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
1d880 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
1d890 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
1d8a0 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
1d8b0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
1d8c0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
1d8d0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
1d8e0 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
1d8f0 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
1d900 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
1d910 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
1d920 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
1d930 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
1d940 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
1d950 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
1d960 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
1d970 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
1d980 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
1d990 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1d9a0 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
1d9b0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
1d9c0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1d9d0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1d9e0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1d9f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
1da00 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1da10 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
1da20 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
1da30 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
1da40 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
1da50 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
1da60 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
1da70 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
1da80 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
1da90 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
1daa0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
1dab0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
1dac0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1dad0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
1dae0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1daf0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1db00 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33  ** [H13741] [H13
1db10 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48  742] [H13743] [H
1db20 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20  13744] [H13745] 
1db30 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38  [H13746] [H13748
1db40 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ].**.** If two o
1db50 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1db60 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1db70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1db80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1db90 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
1dba0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1dbb0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
1dbc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dbd0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
1dbe0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
1dbf0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
1dc00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
1dc10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
1dc20 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1dc30 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1dc40 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1dc50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1dc60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1dc70 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1dc80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1dc90 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
1dca0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1dcb0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
1dcc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1dcd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1dce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1dcf0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
1dd00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1dd10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1dd20 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1dd30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1dd40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1dd50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1dd60 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1dd70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1dd80 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
1dd90 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
1dda0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
1ddb0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
1ddc0 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  760} <S10700>.**
1ddd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
1dde0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
1ddf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1de00 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
1de10 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
1de20 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1de30 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
1de40 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
1de50 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
1de60 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
1de70 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
1de80 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
1de90 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1dea0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
1deb0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
1dec0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
1ded0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
1dee0 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
1def0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
1df00 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
1df10 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1df20 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
1df30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1df40 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
1df50 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1df60 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
1df70 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
1df80 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1df90 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
1dfa0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
1dfb0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
1dfc0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
1dfd0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
1dfe0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
1dff0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1e000 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1e010 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1e020 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
1e030 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
1e040 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
1e050 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
1e060 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
1e070 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
1e080 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
1e090 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
1e0a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
1e0b0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
1e0c0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1e0d0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
1e0e0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
1e0f0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
1e100 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
1e110 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
1e120 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
1e130 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
1e140 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
1e150 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
1e160 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
1e170 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
1e180 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
1e190 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
1e1a0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
1e1b0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
1e1c0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
1e1d0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
1e1e0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
1e1f0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
1e200 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
1e210 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
1e220 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1e230 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b  s:.** [H13761] [
1e240 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d  H13762] [H13763]
1e250 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1e260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1e270 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
1e280 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1e290 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1e2a0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
1e2b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1e2c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1e2d0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
1e2e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1e2f0 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30   {H13200} <S1000
1e300 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0>.**.** After a
1e310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e320 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
1e330 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
1e340 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
1e350 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e360 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e370 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
1e380 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
1e390 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
1e3a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e3b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1e3c0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
1e3d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
1e3e0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
1e3f0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
1e400 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
1e410 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
1e420 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
1e430 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
1e440 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
1e450 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
1e460 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
1e470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
1e480 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
1e490 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
1e4a0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
1e4b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e4c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e4d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1e4e0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
1e4f0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
1e500 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1e510 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
1e520 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
1e530 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
1e540 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
1e550 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
1e560 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
1e570 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
1e580 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
1e590 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
1e5a0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
1e5b0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
1e5c0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1e5d0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
1e5e0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
1e5f0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
1e600 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
1e610 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
1e620 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
1e630 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
1e640 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
1e650 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1e660 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
1e670 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
1e680 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
1e690 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1e6a0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
1e6b0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
1e6c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1e6d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
1e6e0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
1e6f0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
1e700 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
1e710 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
1e720 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
1e730 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
1e740 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
1e750 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
1e760 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
1e770 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1e780 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
1e790 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
1e7a0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
1e7b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
1e7c0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
1e7d0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
1e7e0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
1e7f0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
1e800 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
1e810 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
1e820 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
1e830 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b  tinuing..**.** [
1e840 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
1e850 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
1e860 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
1e870 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
1e880 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
1e890 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
1e8a0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
1e8b0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
1e8c0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
1e8d0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
1e8e0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1e8f0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
1e900 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
1e910 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
1e920 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
1e930 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  state..**.** If 
1e940 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e950 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
1e960 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
1e970 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
1e980 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
1e990 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
1e9a0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
1e9b0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
1e9c0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
1e9d0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
1e9e0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
1e9f0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
1ea00 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
1ea10 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
1ea20 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
1ea30 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
1ea40 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
1ea50 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
1ea60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
1ea70 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
1ea80 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
1ea90 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
1eaa0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
1eab0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
1eac0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
1ead0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
1eae0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
1eaf0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
1eb00 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
1eb10 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
1eb20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
1eb30 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
1eb40 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1eb50 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
1eb60 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
1eb70 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
1eb80 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1eb90 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
1eba0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
1ebb0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
1ebc0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
1ebd0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
1ebe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1ebf0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
1ec00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ec10 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
1ec20 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
1ec30 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
1ec40 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
1ec50 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
1ec60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
1ec70 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
1ec80 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
1ec90 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
1eca0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
1ecb0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
1ecc0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
1ecd0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
1ece0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1ecf0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
1ed00 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
1ed10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1ed20 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
1ed30 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
1ed40 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
1ed50 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
1ed60 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
1ed70 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
1ed80 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
1ed90 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
1eda0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1edb0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
1edc0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
1edd0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
1ede0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
1edf0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
1ee00 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
1ee10 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
1ee20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
1ee30 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
1ee40 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
1ee50 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
1ee60 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
1ee70 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
1ee80 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
1ee90 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
1eea0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1eeb0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
1eec0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
1eed0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
1eee0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1eef0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
1ef00 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
1ef10 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
1ef20 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1ef30 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
1ef40 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
1ef50 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
1ef60 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
1ef70 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
1ef80 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
1ef90 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
1efa0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
1efb0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
1efc0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
1efd0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
1efe0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
1eff0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1f000 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f010 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1f020 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
1f030 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
1f040 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
1f050 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1f060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f070 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
1f080 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
1f090 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
1f0a0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
1f0b0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
1f0c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
1f0d0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
1f0e0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
1f0f0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
1f100 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ded..**.** Requi
1f110 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1f120 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48  202] [H15304] [H
1f130 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20  15306] [H15308] 
1f140 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20  [H15310].*/.int 
1f150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
1f160 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1f170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f180 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1f190 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  in a result set 
1f1a0 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30  {H13770} <S10700
1f1b0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  >.**.** Returns 
1f1c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
1f1d0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
1f1e0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
1f1f0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
1f200 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1f210 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37  * [H13771] [H137
1f220 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  72].*/.int sqlit
1f230 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
1f240 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1f250 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f260 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
1f270 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32   Datatypes {H102
1f280 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30  65} <S10110><S10
1f290 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  120>.** KEYWORDS
1f2a0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
1f2b0 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65  .** {H10266} Eve
1f2c0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
1f2d0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
1f2e0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
1f2f0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
1f300 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
1f310 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1f320 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
1f330 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
1f340 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
1f350 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
1f360 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
1f370 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b   NULL.** </ul> {
1f380 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1f390 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
1f3a0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
1f3b0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
1f3c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
1f3d0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
1f3e0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
1f3f0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
1f400 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
1f410 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
1f420 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
1f430 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
1f440 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
1f450 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
1f460 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
1f470 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
1f480 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
1f490 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
1f4a0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
1f4b0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
1f4c0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
1f4d0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
1f4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
1f4f0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
1f500 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
1f510 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
1f520 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
1f530 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
1f540 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1f550 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
1f560 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
1f570 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
1f580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1f590 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
1f5a0 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30   A Query {H13800
1f5b0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45  } <S10700>.** KE
1f5c0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
1f5d0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
1f5e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
1f5f0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
1f600 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72  "result set quer
1f610 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  y" interface..**
1f620 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1f630 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
1f640 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
1f650 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
1f660 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
1f670 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
1f680 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63  ery.  In every c
1f690 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
1f6a0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1f6b0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
1f6c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f6d0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
1f6e0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
1f6f0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
1f700 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
1f710 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
1f720 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f730 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
1f740 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
1f750 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1f760 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
1f770 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
1f780 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
1f790 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
1f7a0 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  e returned.  The
1f7b0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
1f7c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
1f7d0 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
1f7e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
1f7f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
1f800 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
1f810 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
1f820 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
1f830 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
1f840 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
1f850 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
1f860 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
1f870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
1f880 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
1f890 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
1f8a0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
1f8b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f8c0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
1f8d0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
1f8e0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
1f8f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
1f900 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f910 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
1f920 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
1f930 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
1f940 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1f950 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
1f960 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
1f970 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1f980 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1f990 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
1f9a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
1f9b0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
1f9c0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
1f9d0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
1f9e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1f9f0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
1fa00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
1fa10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fa20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
1fa30 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
1fa40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
1fa50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1fa60 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
1fa70 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
1fa80 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
1fa90 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
1faa0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
1fab0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1fac0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
1fad0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1fae0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
1faf0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
1fb00 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
1fb10 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
1fb20 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
1fb30 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
1fb40 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
1fb50 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
1fb60 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
1fb70 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
1fb80 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
1fb90 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
1fba0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
1fbb0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1fbc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
1fbd0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
1fbe0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
1fbf0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
1fc00 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
1fc10 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
1fc20 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
1fc30 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
1fc40 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
1fc50 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1fc60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
1fc70 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1fc80 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
1fc90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1fca0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
1fcb0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
1fcc0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
1fcd0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
1fce0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
1fcf0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
1fd00 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
1fd10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
1fd20 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
1fd30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
1fd40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fd50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1fd60 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
1fd70 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
1fd80 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
1fd90 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
1fda0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
1fdb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
1fdc0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
1fdd0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
1fde0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
1fdf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1fe00 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
1fe10 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
1fe20 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
1fe30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
1fe40 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
1fe50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
1fe60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
1fe70 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
1fe80 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
1fe90 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
1fea0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1feb0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
1fec0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fed0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
1fee0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
1fef0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
1ff00 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
1ff10 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
1ff20 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
1ff30 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
1ff40 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
1ff50 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
1ff60 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1ff70 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1ff80 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
1ff90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
1ffa0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
1ffb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1ffc0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
1ffd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
1ffe0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
1fff0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
20000 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
20010 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
20020 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
20030 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
20040 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  OB is an arbitra
20050 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
20060 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
20070 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20080 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
20090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
200a0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
200b0 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
200c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
200d0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
200e0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
200f0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
20100 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
20110 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65  UTF-8..** The ze
20120 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73  ro terminator is
20130 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e   not included in
20140 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a   this count..**.
20150 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65  ** The object re
20160 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20170 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
20180 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
20190 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
201a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
201b0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
201c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
201d0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
201e0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
201f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20200 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
20210 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
20220 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
20230 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20240 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
20250 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
20260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
20270 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
20280 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
20290 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
202a0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
202b0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
202c0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
202d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
202e0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
202f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
20300 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
20310 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
20320 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
20330 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
20340 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
20350 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
20360 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
20370 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
20380 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
20390 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
203a0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
203b0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
203c0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
203d0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
203e0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
203f0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
20400 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
20410 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
20420 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
20430 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
20440 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
20450 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
20460 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
20470 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20480 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
20490 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
204a0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
204b0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
204c0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
204d0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
204e0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
204f0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
20500 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20510 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
20520 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
20530 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
20540 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20550 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20560 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
20570 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
20580 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20590 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
205a0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
205b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
205c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
205d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
205e0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
205f0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
20600 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
20610 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
20620 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
20630 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
20640 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
20650 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20660 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20670 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
20680 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
20690 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
206a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
206b0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
206c0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
206d0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
206e0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
206f0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
20700 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
20710 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
20720 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
20730 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
20740 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
20750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
20760 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
20770 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
20780 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
20790 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
207a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
207b0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
207c0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
207d0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
207e0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
207f0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
20800 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
20810 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
20820 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
20830 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
20840 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
20850 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
20860 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
20870 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
20880 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
20890 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
208a0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
208b0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
208c0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
208d0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
208e0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  e>.**.** The tab
208f0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
20900 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
20910 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
20920 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
20930 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
20940 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
20950 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
20960 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
20970 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
20980 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
20990 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
209a0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
209b0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
209c0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
209d0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
209e0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
209f0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
20a00 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
20a10 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
20a20 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
20a30 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
20a40 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
20a50 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
20a60 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
20a70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
20a80 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
20a90 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
20aa0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
20ab0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
20ac0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
20ad0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
20ae0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
20af0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
20b00 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
20b10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
20b20 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
20b30 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
20b40 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
20b50 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
20b60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
20b70 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
20b80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
20b90 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
20ba0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
20bb0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
20bc0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
20bd0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
20be0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
20bf0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
20c00 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
20c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20c20 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
20c30 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
20c40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
20c50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
20c60 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
20c70 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
20c80 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
20c90 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
20ca0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
20cb0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
20cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
20cd0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
20ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20cf0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
20d00 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
20d10 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
20d20 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
20d30 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
20d40 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
20d50 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
20d60 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
20d70 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
20d80 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
20d90 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
20da0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
20db0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
20dc0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
20dd0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
20de0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
20df0 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
20e00 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
20e10 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
20e20 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
20e30 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
20e40 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
20e50 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
20e60 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
20e70 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
20e80 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
20e90 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
20ea0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
20eb0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
20ec0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
20ed0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
20ee0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
20ef0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
20f00 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
20f10 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
20f20 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
20f30 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
20f40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
20f50 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
20f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
20f70 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
20f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20f90 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
20fa0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
20fb0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
20fc0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
20fd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
20fe0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
20ff0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
21000 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
21010 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
21020 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
21030 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
21040 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
21050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21060 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
21070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
21080 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
21090 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
210a0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
210b0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
210c0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
210d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
210e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
210f0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
21100 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
21110 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
21120 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
21130 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21140 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
21150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21160 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
21170 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
21180 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
21190 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
211a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
211b0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
211c0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
211d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
211e0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  es()..**.** The 
211f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
21200 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
21210 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
21220 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
21230 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
21240 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
21250 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
21260 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21270 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21280 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
21290 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f  alled.  The memo
212a0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
212b0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
212c0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
212d0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
212e0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
212f0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
21300 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
21310 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21320 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
21330 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
21340 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
21350 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
21360 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
21370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
21380 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
21390 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
213a0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
213b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
213c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
213d0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
213e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
213f0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
21400 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
21410 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
21420 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
21430 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
21440 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
21450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
21460 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
21470 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
21480 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  OMEM]..**.** Req
21490 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
214a0 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20  13803] [H13806] 
214b0 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32  [H13809] [H13812
214c0 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38  ] [H13815] [H138
214d0 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31  18] [H13821] [H1
214e0 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37  3824].** [H13827
214f0 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f  ] [H13830].*/.co
21500 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21510 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
21520 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21530 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
21540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21550 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21560 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
21570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21580 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
21590 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
215a0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
215b0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
215c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
215d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
215e0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
215f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21600 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
21610 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
21620 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
21630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21640 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
21650 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
21660 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
21670 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21680 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
21690 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
216a0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
216b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
216c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
216d0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
216e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
216f0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
21700 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
21710 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
21720 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21730 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
21740 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
21750 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
21760 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30  t Object {H13300
21770 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30  } <S70300><S3010
21780 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
21790 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
217a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
217b0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
217c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
217d0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  nt]..** If the s
217e0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65  tatement was exe
217f0 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
21800 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  ly or not execut
21810 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a  ed at all, then.
21820 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  ** SQLITE_OK is 
21830 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65  returned. If exe
21840 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
21850 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
21860 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72  hen an.** [error
21870 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
21880 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
21890 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
218a0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
218b0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
218c0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
218d0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
218e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  of the.** [prepa
218f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21900 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   If the virtual 
21910 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
21920 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
21930 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
21940 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
21950 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
21960 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
21970 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
21980 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
21990 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
219a0 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
219b0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
219c0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
219d0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
219e0 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  led,.** dependin
219f0 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
21a00 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a  tances, and the.
21a10 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
21a20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
21a30 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
21a40 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
21a50 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d  nts:.** [H11302]
21a60 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74   [H11304].*/.int
21a70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
21a80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
21a90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
21aa0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
21ab0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
21ac0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
21ad0 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  30} <S70300>.**.
21ae0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
21af0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
21b00 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
21b10 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
21b20 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
21b30 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
21b40 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
21b50 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
21b60 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
21b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
21b80 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
21b90 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
21ba0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
21bb0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21bc0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
21bd0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
21be0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
21bf0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
21c00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
21c10 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
21c20 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
21c30 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {H11332} The [s
21c40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
21c50 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
21c60 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
21c70 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
21c80 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
21c90 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
21ca0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
21cb0 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66  *.** {H11334} If
21cc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
21cd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
21ce0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
21cf0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
21d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21d10 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
21d20 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
21d30 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
21d40 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
21d50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21d60 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
21d70 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
21d80 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  n S,.**         
21d90 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
21da0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
21db0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
21dc0 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20  .** {H11336} If 
21dd0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21de0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21df0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
21e00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
21e10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21e20 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
21e30 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
21e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21e50 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
21e60 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
21e70 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
21e80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d  ..**.** {H11338}
21e90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
21ea0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
21eb0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
21ec0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
21ed0 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
21ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21ef0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
21f00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21f10 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
21f20 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
21f30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
21f40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
21f50 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
21f60 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
21f70 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30  unctions {H16100
21f80 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
21f90 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
21fa0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
21fb0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
21fc0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
21fd0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
21fe0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
21ff0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
22000 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
22010 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
22020 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
22030 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
22040 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
22050 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
22060 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
22070 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
22080 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
22090 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
220a0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
220b0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
220c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
220d0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
220e0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
220f0 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
22100 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
22110 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22120 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
22130 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
22140 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
22150 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
22160 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
22170 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
22180 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
22190 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
221a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
221b0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
221c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
221d0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
221e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
221f0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
22200 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
22210 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
22220 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75  single program u
22230 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
22240 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
22250 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61  nnection interna
22260 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75  lly, then SQL fu
22270 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
22280 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
22290 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61  ly to.** each da
222a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
222b0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
222c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
222d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
222e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
222f0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
22300 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68  * redefined.  Th
22310 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
22320 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
22330 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
22340 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
22350 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
22360 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
22370 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
22380 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
22390 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
223a0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
223b0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
223c0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
223d0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
223e0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
223f0 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20  TE_ERROR] being 
22400 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
22410 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
22420 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
22430 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
22440 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
22450 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
22460 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
22470 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
22480 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
22490 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
224a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
224b0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
224c0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
224d0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
224e0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
224f0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
22500 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
22510 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
22520 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
22530 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
22540 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
22550 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
22560 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
22570 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
22580 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
22590 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
225a0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
225b0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
225c0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
225d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
225e0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
225f0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
22600 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
22610 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
22620 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
22630 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
22640 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
22650 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
22660 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
22670 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
22680 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
22690 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
226a0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
226b0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
226c0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
226d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
226e0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
226f0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
22700 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
22710 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
22720 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
22730 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
22740 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
22750 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
22760 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
22770 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
22780 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
22790 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
227a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
227b0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
227c0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
227d0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
227e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
227f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
22800 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
22810 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
22820 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
22830 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
22840 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
22850 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
22860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
22870 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
22880 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
22890 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
228a0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
228b0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
228c0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
228d0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
228e0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
228f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
22900 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
22910 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
22920 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
22930 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
22940 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
22950 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
22960 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
22970 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
22980 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
22990 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
229a0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
229b0 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
229c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
229d0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
229e0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
229f0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
22a00 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
22a10 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
22a20 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
22a30 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
22a40 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
22a50 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
22a60 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
22a70 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
22a80 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
22a90 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
22aa0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
22ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
22ac0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
22ad0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
22ae0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
22af0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
22b00 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
22b10 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
22b20 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
22b30 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
22b40 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
22b50 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
22b60 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
22b70 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
22b80 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
22b90 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
22ba0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20  ion is used.  A 
22bb0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
22bc0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
22bd0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
22be0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
22bf0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
22c00 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
22c10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
22c20 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
22c30 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74  e nArg.  A funct
22c40 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
22c50 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
22c60 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
22c70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
22c80 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
22c90 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
22ca0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
22cb0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
22cc0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
22cd0 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  * A function whe
22ce0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
22cf0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
22d00 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
22d10 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
22d20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
22d30 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
22d40 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
22d50 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
22d60 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
22d70 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
22d80 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   Built-in functi
22d90 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
22da0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
22db0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22dc0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54   functions..** T
22dd0 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61  he first applica
22de0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
22df0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76  ction with a giv
22e00 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65  en name override
22e10 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69  s all.** built-i
22e20 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  n functions in t
22e30 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
22e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69  e connection] wi
22e50 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
22e60 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
22e70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
22e80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66  ned functions of
22e90 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f   the same name o
22ea0 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a  nly override .**
22eb0 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69   prior applicati
22ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
22ed0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e  ions that are an
22ee0 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72   exact match for
22ef0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
22f00 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  f parameters and
22f10 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64   preferred encod
22f20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70  ing..**.** An ap
22f30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
22f40 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
22f50 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
22f60 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
22f70 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
22f80 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
22f90 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
22fa0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
22fb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
22fc0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
22fd0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
22fe0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
22ff0 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
23000 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
23010 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
23020 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31  .** [H16103] [H1
23030 36 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b  6106] [H16109] [
23040 48 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d  H16112] [H16118]
23050 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32   [H16121] [H1612
23060 34 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b  4] [H16127].** [
23070 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d  H16130] [H16133]
23080 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33   [H16136] [H1613
23090 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69  9] [H16142].*/.i
230a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
230b0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
230c0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
230d0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
230e0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
230f0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
23100 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
23110 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
23120 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
23130 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
23140 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
23150 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
23160 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
23170 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
23180 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
23190 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
231a0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
231b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
231c0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
231d0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
231e0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
231f0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
23200 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
23210 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
23220 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
23230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
23240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
23250 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
23260 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
23270 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
23280 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
23290 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
232a0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
232b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
232c0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
232d0 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e  H10267} <S50200>
232e0 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H16100>.**.** 
232f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
23300 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
23310 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
23320 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
23330 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
23340 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
23350 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
23360 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
23370 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
23380 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
23390 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
233a0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
233b0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
233c0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
233d0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
233e0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
233f0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
23400 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
23410 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
23420 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
23430 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
23440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
23450 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
23460 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
23470 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
23480 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
23490 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
234a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
234b0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
234c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
234d0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
234e0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
234f0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
23500 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
23510 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
23520 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
23530 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
23540 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
23550 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
23560 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
23570 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
23580 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
23590 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
235a0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
235b0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
235c0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
235d0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
235e0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
235f0 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
23600 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
23610 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
23620 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
23630 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
23640 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
23650 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
23660 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23670 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
23680 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
23690 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
236a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
236b0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
236c0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
236d0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
236e0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
236f0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
23700 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
23710 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
23720 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
23730 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
23740 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
23750 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23760 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
23770 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
23780 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
23790 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
237a0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
237b0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
237c0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
237d0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
237e0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
237f0 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30  es {H15100} <S20
23800 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  200>.**.** The C
23810 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
23820 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
23830 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
23840 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
23850 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
23860 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
23870 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
23880 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
23890 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
238a0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
238b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
238c0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
238d0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
238e0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
238f0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
23900 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
23910 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
23920 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
23930 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
23940 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
23950 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
23960 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
23970 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
23980 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
23990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
239a0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
239b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
239c0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
239d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
239e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
239f0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
23a00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
23a10 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
23a20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
23a30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
23a40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
23a50 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
23a60 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
23a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
23a80 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
23a90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
23aa0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
23ab0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
23ac0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
23ad0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
23ae0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
23af0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
23b00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
23b10 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
23b20 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
23b30 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
23b40 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
23b50 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
23b60 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
23b70 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
23b80 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
23b90 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
23ba0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
23bb0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
23bc0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
23bd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
23be0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
23bf0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
23c00 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
23c10 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
23c20 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
23c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23c40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
23c50 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
23c60 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
23c70 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
23c80 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
23c90 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
23ca0 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
23cb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
23cc0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
23cd0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
23ce0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
23cf0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
23d00 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
23d10 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
23d20 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
23d30 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
23d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
23d50 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
23d60 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
23d70 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
23d80 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
23d90 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
23da0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
23db0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
23dc0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
23dd0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
23de0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
23df0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
23e00 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
23e10 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
23e20 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
23e30 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
23e40 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
23e50 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
23e60 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
23e70 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
23e80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
23e90 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
23ea0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
23eb0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
23ec0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
23ed0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
23ee0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
23ef0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
23f00 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
23f10 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
23f20 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
23f30 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
23f40 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
23f50 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
23f60 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
23f70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
23f80 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
23f90 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
23fa0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
23fb0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
23fc0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
23fd0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
23fe0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
23ff0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
24000 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
24010 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24020 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
24030 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24040 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
24050 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
24060 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
24070 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
24080 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
24090 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
240a0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
240b0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
240c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  rs..**.** Requir
240d0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31  ements:.** [H151
240e0 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31  03] [H15106] [H1
240f0 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b  5109] [H15112] [
24100 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d  H15115] [H15118]
24110 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32   [H15121] [H1512
24120 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b  4].** [H15127] [
24130 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d  H15130] [H15133]
24140 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e   [H15136].*/.con
24150 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24160 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
24170 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
24180 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
24190 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
241a0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
241b0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
241c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
241d0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
241e0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
241f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
24200 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
24210 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
24220 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
24230 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
24240 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
24250 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
24260 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
24270 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
24280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24290 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
242a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
242b0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
242c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
242d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
242e0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
242f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
24300 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
24310 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
24320 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
24330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
24340 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
24350 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
24360 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
24370 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
24380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24390 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
243a0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
243b0 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c  ntext {H16210} <
243c0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
243d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
243e0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
243f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
24400 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
24410 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74  allocate.** a st
24420 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72  ructure for stor
24430 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
24440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
24450 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
24460 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
24470 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ext() routine is
24480 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a   called for a.**
24490 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
244a0 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
244b0 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
244c0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
244d0 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d   out that.** mem
244e0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
244f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
24500 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20  . On second and 
24510 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
24520 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
24530 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
24540 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
24550 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
24560 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65  on index,.** the
24570 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
24580 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d  returned. The im
24590 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
245a0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
245b0 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74  n use.** the ret
245c0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
245d0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
245e0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75  .**.** SQLite au
245f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
24600 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  s the allocated 
24610 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20  buffer when the 
24620 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
24630 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
24640 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
24650 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
24660 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
24670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
24680 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
24690 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
246a0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
246b0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
246c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
246d0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
246e0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
246f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
24700 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
24710 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
24720 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
24730 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
24740 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
24750 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
24760 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
24770 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
24780 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48  211] [H16213] [H
24790 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a  16215] [H16217].
247a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
247b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
247c0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
247d0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
247e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
247f0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
24800 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
24810 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
24820 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24830 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
24840 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
24850 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
24860 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
24870 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
24880 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
24890 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
248a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
248b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
248c0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
248d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
248e0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
248f0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
24900 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
24910 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
24920 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
24930 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
24940 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
24950 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
24960 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
24970 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
24980 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
24990 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
249a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
249b0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
249c0 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  243].*/.void *sq
249d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
249e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
249f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24a00 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
24a10 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
24a20 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c  tions {H16250} <
24a30 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a  S60600><S20200>.
24a40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24a50 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
24a60 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
24a70 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
24a80 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
24a90 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
24aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
24ab0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
24ac0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
24ad0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24ae0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
24af0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24b00 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
24b10 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
24b20 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
24b30 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
24b40 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
24b50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  tion..**.** Requ
24b60 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
24b70 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  6253].*/.sqlite3
24b80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
24b90 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
24ba0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
24bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24bc0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
24bd0 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
24be0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
24bf0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
24c00 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
24c10 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
24c20 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
24c30 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
24c40 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
24c50 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
24c60 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
24c70 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
24c80 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
24c90 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
24ca0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
24cb0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
24cc0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
24cd0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
24ce0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
24cf0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
24d00 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
24d10 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
24d20 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
24d30 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
24d40 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
24d50 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
24d60 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
24d70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
24d80 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
24d90 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
24da0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
24db0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24dc0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
24dd0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
24de0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
24df0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
24e00 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
24e10 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
24e20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
24e30 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
24e40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
24e50 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
24e60 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
24e70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
24e80 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
24e90 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
24ea0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
24eb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
24ec0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
24ed0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
24ee0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
24ef0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
24f00 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
24f10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
24f20 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
24f30 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
24f40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
24f50 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
24f60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
24f70 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
24f80 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
24f90 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
24fa0 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
24fb0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
24fc0 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
24fd0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
24fe0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
24ff0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
25000 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
25010 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
25020 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
25030 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
25040 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
25050 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
25060 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
25070 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
25080 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
25090 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
250a0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
250b0 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
250c0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
250d0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
250e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
250f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25100 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
25110 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
25120 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
25130 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
25140 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
25150 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
25160 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
25170 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
25180 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
25190 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
251a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
251b0 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
251c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
251d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
251e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
251f0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
25200 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
25210 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
25220 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
25230 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
25240 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
25250 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
25260 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
25270 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
25280 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
25290 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
252a0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
252b0 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
252c0 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
252d0 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
252e0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
252f0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
25300 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
25310 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
25320 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
25330 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
25340 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
25350 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
25360 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
25370 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
25380 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
25390 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
253a0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
253b0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
253c0 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
253d0 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
253e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
253f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
25400 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
25410 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
25420 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25430 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
25440 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
25450 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36  ** [H16272] [H16
25460 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48  274] [H16276] [H
25470 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20  16277] [H16278] 
25480 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64  [H16279].*/.void
25490 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
254a0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
254b0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
254c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
254d0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
254e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
254f0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
25500 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
25510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
25520 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
25530 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
25540 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30  or Behavior {H10
25550 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a  280} <S30100>.**
25560 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
25570 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
25580 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
25590 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
255a0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
255b0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
255c0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
255d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
255e0 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
255f0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
25600 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
25610 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
25620 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
25630 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
25640 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
25650 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
25660 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
25670 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
25680 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
25690 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
256a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
256b0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
256c0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
256d0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
256e0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
256f0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
25700 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
25710 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
25720 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
25730 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
25740 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
25750 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
25760 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
25770 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
25780 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
25790 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
257a0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
257b0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
257c0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
257d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
257e0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
257f0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
25800 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
25810 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
25820 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
25830 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
25840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25850 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
25860 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
25870 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20  nction {H16400} 
25880 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
25890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
258a0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
258b0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
258c0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
258d0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
258e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
258f0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
25900 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25910 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
25920 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25930 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
25940 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
25950 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25960 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
25970 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
25980 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
25990 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
259a0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
259b0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
259c0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
259d0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
259e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
259f0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
25a00 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
25a10 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
25a20 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
25a30 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
25a40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25a50 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
25a60 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
25a70 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
25a80 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
25a90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25aa0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
25ab0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
25ac0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
25ad0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
25ae0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
25af0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
25b00 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
25b10 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
25b20 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
25b30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
25b40 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
25b50 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
25b60 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
25b70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25b80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
25b90 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
25ba0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
25bb0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
25bc0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
25bd0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
25be0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
25bf0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
25c00 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
25c10 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
25c20 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
25c30 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
25c40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
25c50 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
25c60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
25c70 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
25c80 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
25c90 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
25ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25cb0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
25cc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
25cd0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
25ce0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
25cf0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
25d00 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
25d10 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51  exception..** SQ
25d20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
25d30 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
25d40 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
25d50 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
25d60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
25d70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
25d80 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
25d90 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
25da0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
25db0 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  .  SQLite interp
25dc0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
25dd0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
25de0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
25df0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
25e00 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a  UTF-8. SQLite.**
25e10 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
25e20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
25e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
25e40 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
25e50 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
25e60 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20   order.  If the 
25e70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25e80 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
25e90 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
25ea0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25eb0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
25ec0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
25ed0 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
25ee0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
25ef0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
25f00 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
25f10 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
25f20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
25f30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25f40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
25f50 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
25f60 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
25f70 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
25f80 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
25f90 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
25fa0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
25fb0 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
25fc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
25fd0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25fe0 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  e..** The sqlite
25ff0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
26000 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
26010 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
26020 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
26030 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
26040 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
26050 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
26060 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
26070 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
26080 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
26090 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
260a0 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
260b0 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
260c0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
260d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
260e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
260f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
26100 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
26110 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
26120 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
26130 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
26140 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
26150 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a    By default,.**
26160 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
26170 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
26180 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63    A subsequent c
26190 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
261a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
261b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
261c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
261d0 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
261e0 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
261f0 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OR..**.** The sq
26200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
26210 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
26220 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
26230 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
26240 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
26250 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
26260 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74  LOB is to long t
26270 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
26280 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26290 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
262a0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
262b0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
262c0 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
262d0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
262e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
262f0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
26300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26310 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
26320 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
26330 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
26340 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26350 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
26360 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
26370 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
26380 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
26390 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
263a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
263b0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
263c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
263d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
263e0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
263f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26400 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
26410 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
26420 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
26430 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
26440 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
26450 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
26460 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
26470 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
26480 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
26490 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
264a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
264b0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
264c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
264d0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
264e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
264f0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
26500 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
26510 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
26520 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
26530 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
26540 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
26550 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
26560 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26570 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
26580 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
26590 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
265a0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
265b0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
265c0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
265d0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
265e0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
265f0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
26600 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  ively..** SQLite
26610 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
26620 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
26630 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
26640 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
26650 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
26660 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26670 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
26680 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
26690 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
266a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
266b0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
266c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
266d0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
266e0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
266f0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
26700 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
26710 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
26720 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
26730 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
26740 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
26750 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
26760 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
26770 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
26780 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
26790 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
267a0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
267b0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
267c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
267d0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
267e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
267f0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
26800 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
26810 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
26820 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
26830 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
26840 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
26850 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
26860 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
26870 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
26880 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
26890 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
268a0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
268b0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
268c0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
268d0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
268e0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
268f0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
26900 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26920 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
26930 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
26940 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
26950 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
26960 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
26970 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
26980 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
26990 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
269a0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
269b0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
269c0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
269d0 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20  he it or call a 
269e0 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20  destructor when 
269f0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
26a00 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
26a10 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
26a20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
26a30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26a40 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
26a50 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
26a60 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
26a70 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
26a80 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
26a90 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
26aa0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
26ab0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
26ac0 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
26ad0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
26ae0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
26af0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
26b00 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
26b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26b20 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
26b30 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
26b40 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
26b50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26b60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
26b70 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
26b80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26b90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
26ba0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
26bb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
26bc0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
26bd0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
26be0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
26bf0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
26c00 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
26c10 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
26c20 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
26c30 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
26c40 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
26c50 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
26c60 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
26c70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
26c80 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
26c90 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70  ut harm..** A [p
26ca0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26cb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
26cc0 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
26cd0 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
26ce0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26cf0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26d00 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
26d10 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
26d20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
26d30 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
26d40 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
26d50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
26d60 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
26d70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
26d80 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
26d90 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
26da0 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
26db0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
26dc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26dd0 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
26de0 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
26df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
26e00 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
26e10 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26e20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ined..**.** Requ
26e30 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
26e40 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d 20 5b  6403] [H16406] [
26e50 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 32 5d  H16409] [H16412]
26e60 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 34 31   [H16415] [H1641
26e70 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 31 36  8] [H16421] [H16
26e80 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 37 5d  424].** [H16427]
26e90 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 34 33   [H16430] [H1643
26ea0 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 31 36  3] [H16436] [H16
26eb0 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 5b 48  439] [H16442] [H
26ec0 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 5d 0a  16445] [H16448].
26ed0 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 31 36  ** [H16451] [H16
26ee0 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 5b 48  454] [H16457] [H
26ef0 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 5d 0a  16460] [H16463].
26f00 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
26f10 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
26f20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
26f30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
26f40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
26f50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
26f60 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
26f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
26f80 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
26f90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26fa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26fb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
26fc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
26fd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
26fe0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
26ff0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
27000 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
27010 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
27020 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
27030 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
27040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27050 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
27060 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
27070 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27080 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
27090 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
270a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
270b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
270c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
270d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
270e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
270f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27100 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
27110 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27120 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
27130 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
27140 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27150 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
27160 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
27170 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
27180 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
271a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
271b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
271c0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
271d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
271e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
271f0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
27200 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
27210 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
27220 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27240 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
27250 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27260 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
27270 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27280 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27290 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
272a0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
272b0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
272c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
272d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
272e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
272f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27300 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
27310 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
27320 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30   {H16600} <S2030
27330 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  0>.**.** These f
27340 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
27350 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
27360 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
27370 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   to the.** [data
27380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27390 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
273a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
273b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
273c0 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c   of the new coll
273d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
273e0 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61  s specified as a
273f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
27400 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
27410 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
27420 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
27430 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27440 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
27450 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
27460 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
27470 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c  ation16(). In al
27480 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
27490 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
274a0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
274b0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
274c0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
274d0 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f  rgument may be o
274e0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
274f0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  nts [SQLITE_UTF8
27500 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  ],.** [SQLITE_UT
27510 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54  F16LE] or [SQLIT
27520 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
27530 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
27540 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
27550 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
27560 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
27570 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
27580 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
27590 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
275a0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
275b0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
275c0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
275d0 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
275e0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
275f0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
27600 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
27610 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
27620 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
27630 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
27640 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
27650 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
27660 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
27670 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
27680 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
27690 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a   computer..**.**
276a0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
276b0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
276c0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
276d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
276e0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
276f0 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c    If it is NULL,
27700 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
27710 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
27720 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
27730 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
27740 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
27750 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
27760 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68  .** Each time th
27770 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
27780 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
27790 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
277a0 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
277b0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
277c0 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
277d0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
277e0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
277f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
27800 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
27810 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
27820 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
27830 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
27840 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
27850 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
27860 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
27870 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
27880 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
27890 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
278a0 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
278b0 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
278c0 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
278d0 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
278e0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
278f0 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
27900 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
27910 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
27920 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d  egistered. {END}
27930 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
27940 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
27950 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
27960 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
27970 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
27980 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66  ositive if the f
27990 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
279a0 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75  ess than,.** equ
279b0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
279c0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
279d0 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  d string. i.e. (
279e0 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
279f0 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
27a00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27a10 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
27a20 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
27a30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
27a40 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
27a50 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
27a60 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
27a70 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
27a80 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
27a90 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
27aa0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
27ab0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
27ac0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
27ad0 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
27ae0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
27af0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27b00 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
27b10 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
27b20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27b30 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c  on_v2()..** Coll
27b40 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
27b50 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
27b60 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
27b70 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
27b80 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
27b90 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
27ba0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
27bb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27bc0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
27bd0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
27be0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
27bf0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
27c00 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36  ** [H16603] [H16
27c10 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48  604] [H16606] [H
27c20 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20  16609] [H16612] 
27c30 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38  [H16615] [H16618
27c40 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48  ] [H16621].** [H
27c50 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20  16624] [H16627] 
27c60 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20  [H16630].*/.int 
27c70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27c80 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
27c90 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
27ca0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
27cb0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
27cc0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
27cd0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
27ce0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
27cf0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
27d00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
27d10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
27d20 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
27d30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
27d40 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
27d50 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
27d60 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
27d70 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
27d80 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
27d90 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
27da0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
27db0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
27dc0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
27dd0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
27de0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
27df0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
27e00 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
27e10 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
27e20 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
27e30 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
27e40 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
27e50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
27e60 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
27e70 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d  llbacks {H16700}
27e80 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
27e90 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
27ea0 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
27eb0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
27ec0 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
27ed0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
27ee0 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
27ef0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
27f00 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
27f10 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
27f20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27f30 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65  ion] to be calle
27f40 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
27f50 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
27f60 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
27f70 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
27f80 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   If the function
27f90 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
27fa0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
27fb0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
27fc0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
27fd0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
27fe0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
27ff0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
28000 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
28010 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
28020 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33  n UTF-8. {H16703
28030 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  } If sqlite3_col
28040 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
28050 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
28060 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
28070 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
28080 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
28090 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20  yte order..** A 
280a0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
280b0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
280c0 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61   any existing ca
280d0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
280e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
280f0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
28100 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
28110 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
28120 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
28130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
28140 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
28150 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
28160 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
28170 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
28180 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
28190 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
281a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
281b0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
281c0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
281d0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
281e0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
281f0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
28200 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
28210 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
28220 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
28230 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
28240 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
28250 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
28260 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28270 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
28280 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
28290 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
282a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  e..**.** The cal
282b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
282c0 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
282d0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
282e0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
282f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28300 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
28310 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28320 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
28330 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
28340 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
28350 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
28360 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30  ments:.** [H1670
28370 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36  2] [H16704] [H16
28380 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  706].*/.int sqli
28390 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
283a0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
283b0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
283c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
283d0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
283e0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
283f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
28400 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
28410 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
28420 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
28430 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
28440 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
28450 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
28460 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
28470 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
28480 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
28490 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
284a0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
284b0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
284c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
284d0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
284e0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
284f0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
28500 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
28510 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
28520 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
28530 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
28540 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
28560 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
28570 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
28580 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
28590 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
285a0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
285b0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
285c0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
285d0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
285e0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
285f0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
28600 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
28610 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
28620 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
28630 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
28640 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
28650 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
28660 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
28670 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
28680 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
28690 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
286a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
286b0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
286c0 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
286d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
286e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
286f0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
28700 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
28710 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
28720 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
28730 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
28740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28750 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
28760 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
28770 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34  e {H10530} <S404
28780 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  10>.**.** The sq
28790 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
287a0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
287b0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
287c0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
287d0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
287e0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
287f0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
28800 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
28810 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28820 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
28830 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
28840 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
28850 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
28860 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
28870 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
28880 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
28890 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
288a0 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
288b0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
288c0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
288d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
288e0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
288f0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
28900 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
28910 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
28920 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
28930 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
28940 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
28950 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
28960 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
28970 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
28980 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  object..**.** Re
28990 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
289a0 35 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f  533] [H10536].*/
289b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
289c0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
289d0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
289e0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
289f0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
28a00 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53  iles {H10310} <S
28a10 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  20000>.**.** If 
28a20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
28a30 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
28a40 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
28a50 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
28a60 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
28a70 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
28a80 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
28a90 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
28aa0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
28ab0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
28ac0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
28ad0 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
28ae0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
28af0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
28b00 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
28b10 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
28b20 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
28b30 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
28b40 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
28b50 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
28b60 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
28b70 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
28b80 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
28b90 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
28ba0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
28bb0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
28bc0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
28bd0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
28be0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28bf0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
28c00 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
28c10 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
28c20 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
28c30 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
28c40 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
28c50 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
28c60 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
28c70 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
28c80 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
28c90 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
28ca0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
28cb0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
28cc0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
28cd0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
28ce0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
28cf0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  eafter..**.** Th
28d00 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
28d10 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
28d20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
28d30 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
28d40 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
28d50 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
28d60 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
28d70 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72  e3_malloc].  Fur
28d80 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
28d90 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
28da0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
28db0 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
28dc0 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
28dd0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
28de0 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
28df0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
28e00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
28e10 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
28e20 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
28e30 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
28e40 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
28e50 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
28e60 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
28e70 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
28e80 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
28e90 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
28ea0 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
28eb0 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
28ec0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
28ed0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
28ee0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
28ef0 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
28f00 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
28f10 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
28f20 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
28f30 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
28f40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
28f50 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
28f60 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
28f70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28f80 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
28f90 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32  Commit Mode {H12
28fa0 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  930} <S60200>.**
28fb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
28fc0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
28fd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
28fe0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
28ff0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29000 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
29010 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
29020 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
29030 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
29040 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
29050 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
29060 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f  ctively.  Autoco
29070 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
29080 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41  by default..** A
29090 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
290a0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
290b0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
290c0 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
290d0 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
290e0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
290f0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
29100 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
29110 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
29120 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
29130 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
29140 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
29150 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
29160 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
29170 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
29180 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
29190 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
291a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
291b0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
291c0 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
291d0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
291e0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
291f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
29200 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
29210 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
29220 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
29230 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
29240 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
29250 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
29260 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
29270 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
29280 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
29290 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
292a0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
292b0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
292c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
292d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
292e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
292f0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
29300 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
29310 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
29320 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
29330 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48  nts: [H12931] [H
29340 31 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20  12932] [H12933] 
29350 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20  [H12934].*/.int 
29360 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
29370 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
29380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29390 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
293a0 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
293b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
293c0 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36  ent {H13120} <S6
293d0 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0600>.**.** The 
293e0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
293f0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
29400 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
29410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
29420 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
29430 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29440 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
29450 20 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20    The [database 
29460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
29470 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29480 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
29490 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
294a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
294b0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
294c0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
294d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
294e0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
294f0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
29500 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
29510 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
29520 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
29530 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
29540 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29550 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a  ts: [H13123].*/.
29560 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
29570 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
29580 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29590 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
295a0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
295b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed statement {H1
295c0 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a  3140} <S60600>.*
295d0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
295e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
295f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
29600 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
29610 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
29620 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
29630 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
29640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29650 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69  pDb.  If pStmt i
29660 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
29670 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
29680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
29690 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
296a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
296b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
296c0 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
296d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
296e0 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20   If no prepared 
296f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
29700 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
29710 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
29720 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
29730 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
29740 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29750 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
29760 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
29770 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
29780 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
29790 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
297a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
297b0 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
297c0 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
297d0 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
297e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  nter..**.** Requ
297f0 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34  irements: [H1314
29800 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33  3] [H13146] [H13
29810 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f  149] [H13152].*/
29820 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
29830 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
29840 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
29850 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29860 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29870 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
29880 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
29890 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
298a0 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30   {H12950} <S6040
298b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
298c0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
298d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
298e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
298f0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
29900 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
29910 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
29920 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
29930 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
29940 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
29950 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
29960 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
29970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
29980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29990 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
299a0 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  en..** The sqlit
299b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
299c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
299d0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
299e0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
299f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
29a00 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
29a10 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
29a20 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
29a30 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
29a40 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
29a50 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
29a60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
29a70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29a80 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
29a90 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20  en..** The pArg 
29aa0 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
29ab0 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
29ac0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49  e callback..** I
29ad0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
29ae0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
29af0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
29b00 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
29b10 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
29b20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
29b30 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
29b40 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
29b50 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
29b60 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
29b70 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c   its.** pArg val
29b80 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
29b90 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
29ba0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
29bb0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
29bc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
29bd0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
29be0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
29bf0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
29c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29c10 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
29c20 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20   callback.  Any 
29c30 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
29c40 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
29c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
29c60 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
29c70 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
29c80 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
29c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
29ca0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
29cb0 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d  iggered the comm
29cc0 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63  it.** or rollbac
29cd0 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69  k hook in the fi
29ce0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f  rst place..** No
29cf0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
29d00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
29d10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
29d20 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
29d30 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
29d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
29d50 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
29d60 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
29d70 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
29d80 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61  ** Registering a
29d90 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
29da0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
29db0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
29dc0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
29dd0 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
29de0 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
29df0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
29e00 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
29e10 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
29e20 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
29e30 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
29e40 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
29e50 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
29e60 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
29e70 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
29e80 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
29e90 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
29ea0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
29eb0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
29ec0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
29ed0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
29ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
29ef0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
29f00 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
29f10 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
29f20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
29f30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
29f40 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
29f50 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
29f60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
29f70 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
29f80 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
29f90 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
29fa0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
29fb0 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32  ** [H12951] [H12
29fc0 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48  952] [H12953] [H
29fd0 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a  12954] [H12955].
29fe0 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32  ** [H12961] [H12
29ff0 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48  962] [H12963] [H
2a000 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12964].*/.void *
2a010 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2a020 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
2a030 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
2a040 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
2a050 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2a060 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
2a070 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
2a080 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a090 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
2a0a0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2a0b0 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d  llbacks {H12970}
2a0c0 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
2a0d0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2a0e0 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2a0f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2a100 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2a110 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2a120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a130 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2a140 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2a150 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2a160 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2a170 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2a180 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2a190 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
2a1a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2a1b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2a1c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2a1d0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2a1e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a1f0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2a200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2a210 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2a220 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2a230 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2a240 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2a250 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2a260 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2a270 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2a280 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2a290 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2a2a0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2a2b0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2a2c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2a2d0 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
2a2e0 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
2a2f0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2a300 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2a310 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
2a320 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
2a330 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
2a340 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
2a350 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
2a360 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
2a370 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
2a380 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2a390 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2a3a0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2a3b0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2a3c0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2a3d0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2a3e0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2a3f0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2a400 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
2a410 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2a420 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
2a430 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20   the row..** In 
2a440 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2a450 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2a460 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2a470 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2a480 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
2a490 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2a4a0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
2a4b0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
2a4c0 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
2a4d0 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
2a4e0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
2a4f0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
2a500 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  e)..**.** The up
2a510 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d  date hook implem
2a520 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2a530 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2a540 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2a550 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2a560 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2a570 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74  nvoked the updat
2a580 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74  e hook.  Any act
2a590 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2a5a0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2a5b0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2a5c0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2a5d0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2a5e0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2a5f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a600 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2a610 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20  ered the update 
2a620 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  hook..** Note th
2a630 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
2a640 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
2a650 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
2a660 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
2a670 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2a680 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
2a690 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
2a6a0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
2a6b0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66  agraph..**.** If
2a6c0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
2a6d0 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
2a6e0 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
2a6f0 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69   pArg value.** i
2a700 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
2a710 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
2a720 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  eturned..**.** R
2a730 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
2a740 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33  [H12971] [H12973
2a750 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39  ] [H12975] [H129
2a760 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31  77] [H12979] [H1
2a770 32 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b  2981] [H12983] [
2a780 48 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20  H12986].*/.void 
2a790 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
2a7a0 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
2a7b0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
2a7c0 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
2a7d0 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
2a7e0 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
2a7f0 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
2a800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2a810 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2a820 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
2a830 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33  che {H10330} <S3
2a840 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0900>.** KEYWORD
2a850 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
2a860 7d 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 20  } {shared cache 
2a870 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  mode}.**.** This
2a880 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
2a890 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
2a8a0 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
2a8b0 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
2a8c0 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
2a8d0 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
2a8e0 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  ween [database c
2a8f0 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e  onnection | conn
2a900 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74  ections].** to t
2a910 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2a920 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  . Sharing is ena
2a930 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2a940 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20  ment is true.** 
2a950 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
2a960 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2a970 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63  false..**.** Cac
2a980 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
2a990 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
2a9a0 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
2a9b0 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
2a9c0 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
2a9d0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
2a9e0 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
2a9f0 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
2aa00 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
2aa10 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
2aa20 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
2aa30 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
2aa40 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
2aa50 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
2aa60 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
2aa70 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
2aa80 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
2aa90 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
2aaa0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2aab0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2aac0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2aad0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
2aae0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
2aaf0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
2ab00 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
2ab10 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
2ab20 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
2ab30 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
2ab40 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
2ab50 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
2ab60 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
2ab70 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
2ab80 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61  cache.  When sha
2ab90 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
2aba0 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
2abb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2abc0 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20  ule()] API used 
2abd0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
2abe0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
2abf0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
2ac00 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
2ac10 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
2ac20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2ac30 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
2ac40 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
2ac50 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
2ac60 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
2ac70 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2ac80 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
2ac90 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
2aca0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
2acb0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
2acc0 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
2acd0 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
2ace0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
2acf0 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
2ad00 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
2ad10 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
2ad20 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
2ad30 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
2ad40 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  tly..**.** See A
2ad50 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
2ad60 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
2ad70 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2ad80 6e 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48  nts: [H10331] [H
2ad90 31 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20  10336] [H10337] 
2ada0 5b 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20  [H10339].*/.int 
2adb0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
2adc0 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
2add0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ade0 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72  F: Attempt To Fr
2adf0 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b  ee Heap Memory {
2ae00 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30 3e  H17340} <S30220>
2ae10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ae20 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2ae30 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
2ae40 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e  tempts to free N
2ae50 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61   bytes.** of hea
2ae60 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
2ae70 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
2ae80 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ential memory al
2ae90 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c  locations.** hel
2aea0 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2aeb0 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d  e library. {END}
2aec0 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
2aed0 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
2aee0 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
2aef0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
2af00 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
2af10 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2af20 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65  emory..** sqlite
2af30 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2af40 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
2af50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
2af60 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
2af70 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
2af80 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
2af90 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
2afa0 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  quested..**.** R
2afb0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2afc0 37 33 34 31 5d 20 5b 48 31 37 33 34 32 5d 0a 2a  7341] [H17342].*
2afd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2afe0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
2aff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b000 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
2b010 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
2b020 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30  {H17350} <S30220
2b030 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2b040 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2b050 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2b060 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2b070 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2b080 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2b090 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2b0a0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2b0b0 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20  QLite..** If an 
2b0c0 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
2b0d0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2b0e0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
2b0f0 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  ed the.** soft h
2b100 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
2b110 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2b120 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
2b130 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   one or.** more 
2b140 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
2b150 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
2b160 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
2b170 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
2b180 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20  **.** The limit 
2b190 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
2b1a0 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71  , because if [sq
2b1b0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2b1c0 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f  mory()].** canno
2b1d0 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  t free sufficien
2b1e0 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
2b1f0 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
2b200 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
2b210 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
2b220 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
2b230 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
2b240 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
2b250 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
2b260 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
2b270 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
2b280 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
2b290 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
2b2a0 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
2b2b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2b2c0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
2b2d0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2b2e0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
2b2f0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
2b300 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
2b310 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2b320 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
2b330 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2b340 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
2b350 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
2b360 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74  ap limit..** But
2b370 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
2b380 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62  p limit cannot b
2b390 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  e honored, execu
2b3a0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
2b3b0 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
2b3c0 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
2b3d0 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
2b3e0 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a  y the limit is.*
2b3f0 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
2b400 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
2b410 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
2b420 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
2b430 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2b440 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
2b450 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
2b460 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
2b470 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
2b480 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
2b490 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2b4a0 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
2b4b0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
2b4c0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
2b4d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2b4e0 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
2b4f0 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
2b500 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
2b510 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20  eads. The value 
2b520 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
2b530 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2b540 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
2b550 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
2b560 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
2b570 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
2b580 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72  reads. In.** ver
2b590 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65  sion 3.5.0 there
2b5a0 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d   is no mechanism
2b5b0 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68   for limiting th
2b5c0 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72  e heap usage for
2b5d0 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74  .** individual t
2b5e0 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  hreads..**.** Re
2b5f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
2b600 48 31 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d  H16351] [H16352]
2b610 20 5b 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35   [H16353] [H1635
2b620 34 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36  4] [H16355] [H16
2b630 33 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  358].*/.void sql
2b640 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
2b650 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  imit(int);../*.*
2b660 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72  * CAPI3REF: Extr
2b670 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
2b680 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
2b690 20 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20   Table {H12850} 
2b6a0 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60300>.**.** T
2b6b0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2b6c0 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
2b6d0 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
2b6e0 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
2b6f0 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
2b700 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
2b710 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
2b720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b730 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
2b740 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
2b750 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2b760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d  .**.** The colum
2b770 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
2b780 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
2b790 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2b7a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a  parameters to.**
2b7b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
2b7c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2b7d0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
2b7e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2b7f0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
2b800 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
2b810 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
2b820 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
2b830 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
2b840 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
2b850 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
2b860 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
2b870 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
2b880 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
2b890 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
2b8a0 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
2b8b0 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
2b8c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2b8d0 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
2b8e0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
2b8f0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
2b900 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
2b910 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2b920 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2b930 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2b940 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2b950 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2b960 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2b970 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2b980 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2b990 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2b9a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
2b9b0 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
2b9c0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
2b9d0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
2b9e0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
2b9f0 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
2ba00 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
2ba10 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2ba20 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65  tion. Any of the
2ba30 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2ba40 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2ba50 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2ba60 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2ba70 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2ba80 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2ba90 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2baa0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2bab0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2bac0 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
2bad0 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
2bae0 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
2baf0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2bb00 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
2bb10 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
2bb20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
2bb30 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
2bb40 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
2bb50 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
2bb60 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
2bb70 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
2bb80 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2bb90 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2bba0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
2bbb0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
2bbc0 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
2bbd0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2bbe0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2bbf0 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
2bc00 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
2bc10 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
2bc20 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2bc30 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2bc40 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
2bc50 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
2bc60 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2bc70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  >.**.** The memo
2bc80 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
2bc90 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
2bca0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2bcb0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c   for the.** decl
2bcc0 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
2bcd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2bce0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
2bcf0 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
2bd00 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
2bd10 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74  SQLite API funct
2bd20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
2bd30 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
2bd40 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
2bd50 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20  view, an [error 
2bd60 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2bd70 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
2bd80 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
2bd90 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
2bda0 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
2bdb0 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
2bdc0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
2bdd0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
2bde0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
2bdf0 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
2be00 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
2be10 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
2be20 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
2be30 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49  clared column. I
2be40 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
2be50 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
2be60 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52  ared [INTEGER PR
2be70 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
2be80 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
2be90 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
2bea0 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c   are set as foll
2beb0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
2bec0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
2bed0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
2bee0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
2bef0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
2bf00 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
2bf10 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
2bf20 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
2bf30 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
2bf40 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a   0.** </pre>.**.
2bf50 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
2bf60 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
2bf70 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
2bf80 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
2bf90 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
2bfa0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2bfb0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
2bfc0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
2bfd0 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
2bfe0 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
2bff0 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
2c000 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2c010 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
2c020 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
2c030 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2c040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
2c050 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2c060 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2c070 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  g())..**.** This
2c080 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2c090 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2c0a0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2c0b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2c0c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2c0d0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2c0e0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2c0f0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2c100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2c110 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2c120 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2c130 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2c140 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2c150 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c160 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2c170 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c180 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2c190 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c1a0 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2c1b0 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2c1c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c1d0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2c1e0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2c1f0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2c200 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2c210 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2c220 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2c230 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2c240 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2c250 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2c260 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2c270 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2c280 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2c290 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2c2a0 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2c2b0 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2c2c0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2c2d0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2c2e0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2c2f0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2c300 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2c310 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2c320 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2c330 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2c340 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2c350 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2c360 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2c370 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48   An Extension {H
2c380 31 32 36 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12600} <S20500>.
2c390 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2c3a0 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
2c3b0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2c3c0 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
2c3d0 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
2c3e0 2a 20 7b 48 31 32 36 30 31 7d 20 54 68 65 20 73  * {H12601} The s
2c3f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2c400 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
2c410 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f  e attempts to lo
2c420 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ad an.**        
2c430 20 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69    SQLite extensi
2c440 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
2c450 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
2c460 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zFile..**.** {H
2c470 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79  12602} The entry
2c480 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
2c490 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20  .**.** {H12603} 
2c4a0 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20  zProc may be 0, 
2c4b0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2c4c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
2c4d0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20  try point.**    
2c4e0 20 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 74        defaults t
2c4f0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
2c500 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
2c510 2a 20 7b 48 31 32 36 30 34 7d 20 54 68 65 20 73  * {H12604} The s
2c520 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2c530 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
2c540 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a  e shall return.*
2c550 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2c560 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2c570 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
2c580 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
2c590 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2c5a0 0a 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49 66 20  .** {H12605} If 
2c5b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2c5c0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
2c5d0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
2c5e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2c5f0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
2c600 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
2c610 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74   shall attempt t
2c620 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  o.**          fi
2c630 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
2c640 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  h error message 
2c650 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
2c660 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
2c670 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20    obtained from 
2c680 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2c690 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 63  )]. {END}  The c
2c6a0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a  alling function.
2c6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f 75  **          shou
2c6c0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
2c6d0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
2c6e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2c6f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20  .**.** {H12606} 
2c700 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2c710 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
2c720 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
2c730 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61      [sqlite3_ena
2c740 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2c750 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
2c760 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
2c770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 68  .**          oth
2c780 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
2c790 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
2c7a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c7b0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2c7c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c7d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
2c7e0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2c7f0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
2c800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
2c810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2c820 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
2c830 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
2c840 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
2c850 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
2c860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
2c870 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
2c880 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
2c890 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
2c8a0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
2c8b0 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
2c8c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
2c8d0 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
2c8e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c8f0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2c900 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
2c910 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 30 7d  Loading {H12620}
2c920 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20500>.**.** 
2c930 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65  So as not to ope
2c940 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73  n security holes
2c950 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63   in older applic
2c960 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a  ations that are.
2c970 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f  ** unprepared to
2c980 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e   deal with exten
2c990 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e  sion loading, an
2c9a0 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20  d as a means of 
2c9b0 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74  disabling.** ext
2c9c0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77  ension loading w
2c9d0 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
2c9e0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
2c9f0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
2ca00 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64  API.** is provid
2ca10 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b  ed to turn the [
2ca20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2ca30 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e  ension()] mechan
2ca40 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a  ism on and off..
2ca50 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20  **.** Extension 
2ca60 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
2ca70 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
2ca80 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a  icket #1863..**.
2ca90 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c  ** {H12621} Call
2caa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
2cab0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2cac0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
2cad0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20  h onoff==1.**   
2cae0 20 20 20 20 20 20 20 74 6f 20 74 75 72 6e 20 65         to turn e
2caf0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2cb00 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20   on and call it 
2cb10 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
2cb20 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20   turn.**        
2cb30 20 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67    it back off ag
2cb40 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ain..**.** {H126
2cb50 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  22} Extension lo
2cb60 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
2cb70 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20  default..*/.int 
2cb80 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
2cb90 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
2cba0 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
2cbb0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
2cbc0 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69  PI3REF: Automati
2cbd0 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78  cally Load An Ex
2cbe0 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30  tensions {H12640
2cbf0 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20500>.**.**
2cc00 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65   This API can be
2cc10 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
2cc20 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
2cc30 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
2cc40 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
2cc50 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
2cc60 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
2cc70 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
2cc80 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
2cc90 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2cca0 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a  ections]. {END}.
2ccb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ccc0 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
2ccd0 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
2cce0 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
2ccf0 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61   that is.** obta
2cd00 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2cd10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49  e3_malloc()].  I
2cd20 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f  f you run a memo
2cd30 72 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a  ry leak checker.
2cd40 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72  ** on your progr
2cd50 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74  am and it report
2cd60 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65  s a leak because
2cd70 20 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c 20   of this array, 
2cd80 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74  invoke.** [sqlit
2cd90 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
2cda0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2cdb0 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20   to shutdown to 
2cdc0 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e  free the memory.
2cdd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20  .**.** {H12641} 
2cde0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
2cdf0 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
2ce00 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
2ce10 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20   that is.**     
2ce20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
2ce30 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  ly invoked whene
2ce40 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62  ver a new [datab
2ce50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2ce60 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f  **          is o
2ce70 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  pened using [sql
2ce80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2ce90 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2cea0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
2ceb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2cec0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  2()]..**.** {H12
2ced0 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65  642} Duplicate e
2cee0 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65  xtensions are de
2cef0 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e  tected so callin
2cf00 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  g this routine.*
2cf10 2a 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69  *          multi
2cf20 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74  ple times with t
2cf30 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f  he same extensio
2cf40 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a  n is harmless..*
2cf50 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68  *.** {H12643} Th
2cf60 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
2cf70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2cf80 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
2cf90 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20  an array.**     
2cfa0 20 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 74       that is obt
2cfb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2cfc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
2cfd0 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75  *.** {H12644} Au
2cfe0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2cff0 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
2d000 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2d010 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
2d020 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
2d030 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76  (*xEntryPoint)(v
2d040 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid));../*.** CA
2d050 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
2d060 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
2d070 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36  n Loading {H1266
2d080 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a  0} <S20500>.**.*
2d090 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
2d0a0 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
2d0b0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2d0c0 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  ed automatic.** 
2d0d0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
2d0e0 7d 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65  }  It undoes the
2d0f0 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
2d100 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rior.** [sqlite3
2d110 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2d120 29 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  )] calls..**.** 
2d130 7b 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 75  {H12661} This fu
2d140 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2d150 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2d160 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
2d170 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20        automatic 
2d180 65 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a  extensions..**.*
2d190 2a 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20  * {H12662} This 
2d1a0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2d1b0 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  s automatic exte
2d1c0 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68  nsions in all th
2d1d0 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
2d1e0 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
2d1f0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
2d200 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  );../*.****** EX
2d210 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
2d220 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
2d230 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
2d240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
2d250 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
2d260 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
2d270 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
2d280 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
2d290 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
2d2a0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
2d2b0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
2d2c0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
2d2d0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
2d2e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
2d2f0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
2d300 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
2d310 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
2d320 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
2d330 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
2d340 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
2d350 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
2d360 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
2d370 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
2d380 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
2d390 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
2d3a0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
2d3b0 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
2d3c0 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20  Structures used 
2d3d0 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  by the virtual t
2d3e0 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  able interface.*
2d3f0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2d400 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71   sqlite3_vtab sq
2d410 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65  lite3_vtab;.type
2d420 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2d430 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71  e3_index_info sq
2d440 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2d450 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2d460 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2d470 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61  rsor sqlite3_vta
2d480 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65  b_cursor;.typede
2d490 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d4a0 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f  _module sqlite3_
2d4b0 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  module;../*.** C
2d4c0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
2d4d0 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48   Table Object {H
2d4e0 31 38 30 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18000} <S20400>.
2d4f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2d500 69 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 20 45  ite3_module.** E
2d510 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2d520 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20  * A module is a 
2d530 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c  class of virtual
2d540 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d   tables.  Each m
2d550 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64  odule is defined
2d560 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e  .** by an instan
2d570 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ce of the follow
2d580 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20  ing structure.  
2d590 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
2d5a0 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c  onsists.** mostl
2d5b0 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
2d5c0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
2d5d0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2d5e0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2d5f0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2d600 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2d610 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2d620 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2d630 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  QLite..*/.struct
2d640 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2d650 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
2d660 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
2d670 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
2d680 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2d690 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2d6a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2d6b0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2d6c0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2d6d0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2d6e0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2d6f0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
2d700 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2d710 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d720 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2d730 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2d740 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d750 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2d760 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2d770 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
2d780 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
2d790 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
2d7a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
2d7b0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
2d7c0 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
2d7d0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d7e0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
2d7f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d800 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
2d810 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2d820 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
2d830 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
2d840 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
2d850 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
2d860 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
2d870 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
2d880 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2d890 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
2d8a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
2d8b0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
2d8c0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2d8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
2d8e0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
2d8f0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
2d900 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
2d910 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
2d920 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
2d930 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
2d940 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
2d950 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
2d960 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2d970 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
2d980 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2d990 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
2d9a0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
2d9b0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
2d9c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
2d9d0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
2d9e0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
2d9f0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
2da00 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
2da10 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2da20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
2da30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2da40 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
2da50 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
2da60 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2da70 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
2da80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2da90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
2daa0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
2dab0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
2dac0 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
2dad0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
2dae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2daf0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
2db00 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2db10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2db20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
2db30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2db40 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
2db50 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
2db60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2db70 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
2db80 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
2db90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
2dba0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
2dbb0 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
2dbc0 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 30 34 30   {H18100} <S2040
2dbd0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
2dbe0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2dbf0 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  fo.** EXPERIMENT
2dc00 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
2dc10 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
2dc20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74  structure and it
2dc30 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20  s substructures 
2dc40 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61  is used to.** pa
2dc50 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ss information i
2dc60 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20  nto and receive 
2dc70 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74  the reply from t
2dc80 68 65 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a  he xBestIndex.**
2dc90 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71   method of an sq
2dca0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54  lite3_module.  T
2dcb0 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
2dcc0 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
2dcd0 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
2dce0 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
2dcf0 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
2dd00 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
2dd10 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
2dd20 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
2dd30 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
2dd40 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
2dd50 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
2dd60 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
2dd70 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
2dd80 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
2dd90 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  <pre>column OP e
2dda0 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  xpr</pre>.**.** 
2ddb0 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26  where OP is =, &
2ddc0 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b  lt;, &lt;=, &gt;
2ddd0 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 65  , or &gt;=.  The
2dde0 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
2ddf0 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
2de00 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
2de10 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
2de20 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2de30 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
2de40 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
2de50 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
2de60 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
2de70 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
2de80 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
2de90 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
2dea0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
2deb0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
2dec0 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
2ded0 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
2dee0 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
2def0 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
2df00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2df10 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
2df20 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
2df30 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
2df40 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
2df50 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
2df60 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
2df70 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
2df80 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
2df90 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
2dfa0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
2dfb0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
2dfc0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
2dfd0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
2dfe0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
2dff0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
2e000 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
2e010 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
2e020 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
2e030 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
2e040 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
2e050 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
2e060 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2e070 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2e080 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
2e090 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
2e0a0 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
2e0b0 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
2e0c0 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
2e0d0 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
2e0e0 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
2e0f0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
2e100 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
2e110 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
2e120 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
2e130 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
2e140 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
2e150 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
2e160 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
2e170 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
2e180 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2e190 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
2e1a0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
2e1b0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
2e1c0 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
2e1d0 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
2e1e0 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
2e1f0 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
2e200 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
2e210 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
2e220 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
2e230 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
2e240 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
2e250 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
2e260 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
2e270 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
2e280 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
2e290 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
2e2a0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
2e2b0 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
2e2c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2e2d0 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
2e2e0 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
2e2f0 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
2e300 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
2e310 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
2e320 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
2e330 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
2e340 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
2e350 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
2e360 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
2e370 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
2e380 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
2e390 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
2e3a0 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
2e3b0 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
2e3c0 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
2e3d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
2e3e0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
2e3f0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
2e400 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
2e410 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
2e420 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
2e430 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
2e440 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
2e450 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
2e460 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
2e470 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
2e480 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
2e490 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
2e4a0 6f 67 28 4e 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  og(N)..**.** Thi
2e4b0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2e4c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2e4d0 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2e4e0 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2e4f0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2e500 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2e510 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2e520 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
2e530 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
2e540 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74   int nConstraint
2e550 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ;           /* N
2e560 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
2e570 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
2e580 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
2e590 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
2e5a0 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20  aint {.     int 
2e5b0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
2e5c0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
2e5d0 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  on left-hand sid
2e5e0 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20  e of constraint 
2e5f0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
2e600 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20   char op;       
2e610 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20    /* Constraint 
2e620 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20  operator */.    
2e630 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75   unsigned char u
2e640 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72  sable;     /* Tr
2e650 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74  ue if this const
2e660 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20  raint is usable 
2e670 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72  */.     int iTer
2e680 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
2e690 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
2e6a0 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
2e6b0 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
2e6c0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
2e6d0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20  int;            
2e6e0 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52  /* Table of WHER
2e6f0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
2e700 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f  ints */.  int nO
2e710 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
2e720 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
2e730 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
2e740 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
2e750 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
2e760 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
2e770 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
2e780 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
2e790 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
2e7a0 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
2e7b0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
2e7c0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
2e7d0 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
2e7e0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61  r ASC. */.  } *a
2e7f0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
2e800 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
2e810 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
2e820 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
2e830 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
2e840 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
2e850 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
2e860 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
2e870 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
2e880 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
2e890 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
2e8a0 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
2e8b0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
2e8c0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
2e8d0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
2e8e0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
2e8f0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
2e900 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
2e910 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
2e920 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
2e930 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
2e940 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
2e950 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
2e960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e970 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
2e980 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2e990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
2e9a0 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
2e9b0 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
2e9c0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
2e9d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
2e9e0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
2e9f0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
2ea00 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
2ea10 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
2ea20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
2ea30 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
2ea40 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
2ea50 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
2ea60 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
2ea70 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
2ea80 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2ea90 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
2eaa0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2eab0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2eac0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
2ead0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2eae0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
2eaf0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2eb00 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2eb10 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
2eb20 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2eb30 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
2eb40 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
2eb50 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2eb60 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
2eb70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb80 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
2eb90 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
2eba0 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d  ntation {H18200}
2ebb0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
2ebc0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
2ebd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
2ebe0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
2ebf0 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
2ec00 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 5b 64 61  me with a.** [da
2ec10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ec20 6e 5d 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65  n].  Module name
2ec30 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
2ec40 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
2ec50 72 65 61 74 69 6e 67 20 6e 65 77 20 76 69 72 74  reating new virt
2ec60 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74 68  ual tables on th
2ec70 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66  e module, or bef
2ec80 6f 72 65 20 75 73 69 6e 67 0a 2a 2a 20 70 72 65  ore using.** pre
2ec90 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
2eca0 20 74 61 62 6c 65 73 20 6f 66 20 74 68 65 20 6d   tables of the m
2ecb0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  odule..**.** Thi
2ecc0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
2ecd0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
2ece0 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2ecf0 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
2ed00 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
2ed10 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2ed20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
2ed30 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
2ed40 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2ed50 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2ed60 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ed70 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
2ed80 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
2ed90 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
2eda0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2edb0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
2edc0 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
2edd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
2ede0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
2edf0 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
2ee00 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
2ee10 20 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20    void *        
2ee20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ee30 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
2ee40 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
2ee50 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2ee60 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
2ee70 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
2ee80 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
2ee90 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30  {H18210} <S20400
2eea0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
2eeb0 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  L.**.** This rou
2eec0 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61  tine is identica
2eed0 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  l to the [sqlite
2eee0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
2eef0 29 5d 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  )] method above,
2ef00 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2ef10 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
2ef20 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2ef30 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
2ef40 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
2ef50 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
2ef60 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
2ef70 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
2ef80 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 53 51 4c  bles API..*/.SQL
2ef90 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
2efa0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2efb0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
2efc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2efd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2efe0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
2eff0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
2f000 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
2f010 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2f020 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
2f030 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
2f040 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
2f050 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
2f060 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
2f070 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
2f080 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
2f090 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
2f0a0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
2f0b0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
2f0c0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2f0d0 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
2f0e0 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
2f0f0 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
2f100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f110 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2f120 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20  Instance Object 
2f130 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30  {H18010} <S20400
2f140 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  >.** KEYWORDS: s
2f150 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45  qlite3_vtab.** E
2f160 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2f170 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69  * Every module i
2f180 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
2f190 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  es a subclass of
2f1a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2f1b0 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64  tructure.** to d
2f1c0 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
2f1d0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
2f1e0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
2f1f0 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
2f200 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
2f210 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
2f220 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
2f230 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
2f240 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
2f250 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
2f260 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
2f270 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
2f280 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
2f290 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
2f2a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2f2b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
2f2c0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
2f2d0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
2f2e0 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
2f2f0 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
2f300 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
2f310 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
2f320 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
2f330 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
2f340 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
2f350 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
2f360 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
2f370 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
2f380 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
2f390 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
2f3a0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
2f3b0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
2f3c0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
2f3d0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
2f3e0 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
2f3f0 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
2f400 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
2f410 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2f420 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
2f430 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2f440 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
2f450 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
2f460 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74  roed.  Note.** t
2f470 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  hat sqlite3_mpri
2f480 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
2f490 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73 65  3_free() are use
2f4a0 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67  d on the zErrMsg
2f4b0 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20   field.** since 
2f4c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61  virtual tables a
2f4d0 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c  re commonly impl
2f4e0 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61  emented in loada
2f4f0 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77  ble extensions w
2f500 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68  hich.** do not h
2f510 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73 71  ave access to sq
2f520 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f  lite3MPrintf() o
2f530 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e  r sqlite3Free().
2f540 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2f550 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
2f560 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
2f570 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
2f580 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
2f590 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2f5a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74  of SQLite..*/.st
2f5b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
2f5c0 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69  b {.  const sqli
2f5d0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64  te3_module *pMod
2f5e0 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64  ule;  /* The mod
2f5f0 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72  ule for this vir
2f600 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20  tual table */.  
2f610 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20  int nRef;       
2f620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f630 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
2f640 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ly */.  char *zE
2f650 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
2f660 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
2f670 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
2f680 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
2f690 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
2f6a0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
2f6b0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
2f6c0 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
2f6d0 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
2f6e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f6f0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2f700 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b  Cursor Object  {
2f710 48 31 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e  H18020} <S20400>
2f720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
2f730 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2f740 72 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  r.** EXPERIMENTA
2f750 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  L.**.** Every mo
2f760 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
2f770 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
2f780 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
2f790 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
2f7a0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
2f7b0 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
2f7c0 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
2f7d0 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
2f7e0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
2f7f0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
2f800 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
2f810 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
2f820 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
2f830 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
2f840 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
2f850 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
2f860 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
2f870 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2f880 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
2f890 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
2f8a0 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
2f8b0 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
2f8c0 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
2f8d0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
2f8e0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
2f8f0 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
2f900 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
2f910 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
2f920 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2f930 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
2f940 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
2f950 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
2f960 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
2f970 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2f980 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  QLite..*/.struct
2f990 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2f9a0 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
2f9b0 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
2f9c0 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
2f9d0 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
2f9e0 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
2f9f0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
2fa00 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
2fa10 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
2fa20 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
2fa30 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
2fa40 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
2fa50 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
2fa60 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32  tual Table {H182
2fa70 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  80} <S20400>.** 
2fa80 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2fa90 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20 61  ** The xCreate a
2faa0 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  nd xConnect meth
2fab0 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20  ods of a module 
2fac0 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  use the followin
2fad0 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c  g API.** to decl
2fae0 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28  are the format (
2faf0 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61  the names and da
2fb00 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63  tatypes of the c
2fb10 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68  olumns) of.** th
2fb20 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
2fb30 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e   they implement.
2fb40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2fb50 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
2fb60 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
2fb70 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
2fb80 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
2fb90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2fba0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
2fbb0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
2fbc0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  L int sqlite3_de
2fbd0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
2fbe0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
2fbf0 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
2fc00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fc10 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
2fc20 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
2fc30 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30  al Table {H18300
2fc40 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
2fc50 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2fc60 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
2fc70 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
2fc80 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
2fc90 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
2fca0 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
2fcb0 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20  e xFindFunction 
2fcc0 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f  method.  But glo
2fcd0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
2fce0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
2fcf0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
2fd00 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
2fd10 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rloaded..**.** T
2fd20 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
2fd30 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
2fd40 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
2fd50 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
2fd60 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
2fd70 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
2fd80 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
2fd90 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
2fda0 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
2fdb0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
2fdc0 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
2fdd0 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
2fde0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2fdf0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
2fe00 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
2fe10 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
2fe20 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
2fe30 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
2fe40 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
2fe50 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
2fe60 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
2fe70 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
2fe80 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
2fe90 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
2fea0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
2feb0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
2fec0 20 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c   by virtual tabl
2fed0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  es..**.** This A
2fee0 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e  PI should be con
2fef0 73 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20  sidered part of 
2ff00 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2ff10 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  e interface,.** 
2ff20 77 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d  which is experim
2ff30 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63  ental and subjec
2ff40 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
2ff50 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
2ff60 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
2ff70 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f  overload_functio
2ff80 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  n(sqlite3*, cons
2ff90 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d  t char *zFuncNam
2ffa0 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f  e, int nArg);../
2ffb0 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
2ffc0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
2ffd0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
2ffe0 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20  m defined above 
2fff0 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61  (back up.** to a
30000 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61   comment remarka
30010 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  bly similar to t
30020 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72  his one) is curr
30030 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
30040 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
30050 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
30060 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
30070 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
30080 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
30090 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
300a0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
300b0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
300c0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
300d0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
300e0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
300f0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
30100 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
30110 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
30120 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
30130 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
30140 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
30150 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
30160 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
30170 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
30180 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
30190 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
301a0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a  *******.*/../*.*
301b0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
301c0 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
301d0 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53  BLOB {H17800} <S
301e0 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  30230>.** KEYWOR
301f0 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  DS: {BLOB handle
30200 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d  } {BLOB handles}
30210 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
30220 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
30230 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
30240 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69  open BLOB on whi
30250 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ch.** [sqlite3_b
30260 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
30270 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
30280 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
30290 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66  d..** Objects of
302a0 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63   this type are c
302b0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
302c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
302d0 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  ** and destroyed
302e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
302f0 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54  b_close()]..** T
30300 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
30310 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
30320 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
30330 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
30340 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
30350 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
30360 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
30370 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
30380 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
30390 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
303a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
303b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
303c0 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  OB in bytes..*/.
303d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
303e0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
303f0 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
30400 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
30410 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
30420 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38  mental I/O {H178
30430 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  10} <S30230>.**.
30440 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
30450 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42  es opens a [BLOB
30460 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65   handle | handle
30470 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f  ] to the BLOB lo
30480 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
30490 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f  iRow, column zCo
304a0 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62  lumn, table zTab
304b0 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
304c0 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20  Db;.** in other 
304d0 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20  words, the same 
304e0 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20  BLOB that would 
304f0 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a  be selected by:.
30500 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
30510 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d     SELECT zColum
30520 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c  n FROM zDb.zTabl
30530 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20  e WHERE [rowid] 
30540 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65  = iRow;.** </pre
30550 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66  > {END}.**.** If
30560 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
30570 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
30580 2c 20 74 68 65 20 74 68 65 20 42 4c 4f 42 20 69  , the the BLOB i
30590 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
305a0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
305b0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
305c0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
305d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
305e0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  d access..**.** 
305f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
30600 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
30610 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
30620 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
30630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
30640 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
30650 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
30660 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
30670 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77  ** is assigned w
30680 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
30690 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
306a0 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
306b0 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   For the main da
306c0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
306d0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
306e0 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72  s "main"..** For
306f0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
30700 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
30710 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
30720 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
30730 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
30740 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
30750 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
30760 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
30770 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
30780 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
30790 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
307a0 6e 64 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  nd any value wri
307b0 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
307c0 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  ob should not be
307d0 20 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c   used by the cal
307e0 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ler..** This fun
307f0 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b  ction sets the [
30800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30810 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ion] error code 
30820 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
30830 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
30840 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
30850 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
30860 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  rrmsg()]..**.** 
30870 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20  If the row that 
30880 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f  a BLOB handle po
30890 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66  ints to is modif
308a0 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50  ied by an.** [UP
308b0 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c  DATE], [DELETE],
308c0 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c   or by [ON CONFL
308d0 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74  ICT] side-effect
308e0 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c  s.** then the BL
308f0 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72  OB handle is mar
30900 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22  ked as "expired"
30910 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75  ..** This is tru
30920 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20  e if any column 
30930 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68  of the row is ch
30940 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f  anged, even a co
30950 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68  lumn.** other th
30960 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42  an the one the B
30970 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70  LOB handle is op
30980 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20  en on..** Calls 
30990 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
309a0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
309b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
309c0 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70  ()] for.** a exp
309d0 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65  ired BLOB handle
309e0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65   fail with an re
309f0 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
30a00 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20  LITE_ABORT]..** 
30a10 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
30a20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
30a30 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
30a40 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
30a50 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 20 74 68  * rollback by th
30a60 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  e expiration of 
30a70 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20  the BLOB.  Such 
30a80 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65  changes will eve
30a90 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69  ntually.** commi
30aa0 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63  t if the transac
30ab0 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74  tion continues t
30ac0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
30ad0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
30ae0 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48  :.** [H17813] [H
30af0 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20  17814] [H17816] 
30b00 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31  [H17819] [H17821
30b10 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e  ] [H17824].*/.in
30b20 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
30b30 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
30b40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30b50 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
30b60 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
30b70 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
30b80 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
30b90 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
30ba0 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
30bb0 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
30bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30bd0 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e  Close A BLOB Han
30be0 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33  dle {H17830} <S3
30bf0 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73  0230>.**.** Clos
30c00 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
30c10 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
30c20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73  Closing a BLOB s
30c30 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63  hall cause the c
30c40 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
30c50 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20  on to commit.** 
30c60 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
30c70 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20  other BLOBs, no 
30c80 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64  pending prepared
30c90 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
30ca0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
30cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69   connection is i
30cc0 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  n [autocommit mo
30cd0 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77  de]..** If any w
30ce0 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
30cf0 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
30d00 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
30d10 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
30d20 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
30d30 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
30d40 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a  ll fit. {END}.**
30d50 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20  .** Closing the 
30d60 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65  BLOB often force
30d70 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a  s the changes.**
30d80 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64   out to disk and
30d90 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65   so if any I/O e
30da0 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65  rrors occur, the
30db0 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63  y will likely oc
30dc0 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69  cur.** at the ti
30dd0 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42  me when the BLOB
30de0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31   is closed.  {H1
30df0 37 38 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73  7833} Any errors
30e00 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
30e10 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
30e20 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
30e30 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
30e40 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
30e50 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
30e60 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
30e70 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
30e80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
30e90 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
30ea0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
30eb0 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  ll closed..**.**
30ec0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
30ed0 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38  * [H17833] [H178
30ee0 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a  36] [H17839].*/.
30ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
30f00 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62  _close(sqlite3_b
30f10 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
30f20 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
30f30 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f  The Size Of An O
30f40 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30  pen BLOB {H17840
30f50 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
30f60 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   Returns the siz
30f70 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
30f80 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c  e BLOB accessibl
30f90 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 0a 2a  e via the open.*
30fa0 2a 20 5b 5d 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  * []BLOB handle]
30fb0 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   in its only arg
30fc0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ument..**.** Req
30fd0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
30fe0 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17843].*/.int sq
30ff0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
31000 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
31010 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31020 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  F: Read Data Fro
31030 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
31040 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20  ntally {H17850} 
31050 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30230>.**.** T
31060 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
31070 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
31080 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b  a from an open [
31090 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74  BLOB handle] int
310a0 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  o a.** caller-su
310b0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
310c0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
310d0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
310e0 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20  uffer Z.** from 
310f0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
31100 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
31110 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
31120 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
31130 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
31140 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
31150 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
31160 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
31170 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
31180 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
31190 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f  ead.  If N or iO
311a0 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
311b0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
311c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
311d0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
311e0 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a  ta is read..**.*
311f0 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  * An attempt to 
31200 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70  read from an exp
31210 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
31220 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
31230 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
31240 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
31250 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
31260 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
31270 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
31280 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
31290 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
312a0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
312b0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
312c0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
312d0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35 33  ents:.** [H17853
312e0 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 37 38  ] [H17856] [H178
312f0 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48 31  59] [H17862] [H1
31300 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d 20 5b  7863] [H17865] [
31310 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20 73  H17868].*/.int s
31320 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
31330 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
31340 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
31350 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
31360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31370 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
31380 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
31390 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c 53  ally {H17870} <S
313a0 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30230>.**.** Thi
313b0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
313c0 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
313d0 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42   into an open [B
313e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d  LOB handle] from
313f0 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
31400 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
31410 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
31420 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
31430 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
31440 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
31450 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
31460 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
31470 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f 42  .** If the [BLOB
31480 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20   handle] passed 
31490 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
314a0 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70  ument was not op
314b0 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74  ened for.** writ
314c0 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
314d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
314e0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
314f0 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20  ] was zero),.** 
31500 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
31510 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
31520 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ADONLY]..**.** T
31530 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
31540 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
31550 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
31560 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20   BLOB; it is.** 
31570 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
31580 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
31590 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e  e of a BLOB usin
315a0 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49  g this API..** I
315b0 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
315c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
315d0 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
315e0 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
315f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
31600 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
31610 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
31620 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a  tten.  If N is.*
31630 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
31640 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
31650 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
31660 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
31670 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74  en..**.** An att
31680 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f  empt to write to
31690 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
316a0 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
316b0 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
316c0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
316d0 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 73  _ABORT].  Writes
316e0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61   to the BLOB tha
316f0 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65  t occurred.** be
31700 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68  fore the [BLOB h
31710 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61  andle] expired a
31720 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61  re not rolled ba
31730 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70  ck by the.** exp
31740 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68  iration of the h
31750 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66  andle, though of
31760 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68   course those ch
31770 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68  anges might.** h
31780 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69  ave been overwri
31790 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74  tten by the stat
317a0 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72  ement that expir
317b0 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ed the BLOB hand
317c0 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65  le.** or by othe
317d0 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74  r independent st
317e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
317f0 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49  On success, SQLI
31800 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
31810 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  d..** Otherwise,
31820 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
31830 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
31840 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
31850 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31860 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
31870 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 38  * [H17873] [H178
31880 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 31  74] [H17875] [H1
31890 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 5b  7876] [H17877] [
318a0 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 5d  H17879] [H17882]
318b0 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 31   [H17885].** [H1
318c0 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7888].*/.int sql
318d0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
318e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
318f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
31900 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
31910 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31920 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c  REF: Virtual Fil
31930 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73  e System Objects
31940 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31 30   {H11200} <S2010
31950 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  0>.**.** A virtu
31960 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
31970 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
31980 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
31990 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
319a0 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
319b0 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
319c0 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
319d0 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
319e0 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
319f0 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
31a00 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
31a10 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
31a20 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
31a30 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
31a40 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
31a50 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
31a60 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
31a70 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
31a80 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
31a90 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
31aa0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
31ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
31ac0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
31ad0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31ae0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
31af0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e  n its name..** N
31b00 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
31b10 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65  nsitive..** Name
31b20 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
31b30 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
31b40 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ngs..** If there
31b50 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20   is no match, a 
31b60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31b70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
31b80 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
31b90 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
31ba0 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
31bb0 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
31bc0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
31bd0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
31be0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
31bf0 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20 62  * Each new VFS b
31c00 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75  ecomes the defau
31c10 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d 61  lt VFS if the ma
31c20 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73  keDflt flag is s
31c30 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20  et..** The same 
31c40 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
31c50 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
31c60 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
31c70 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20  ury..** To make 
31c80 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
31c90 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74  into the default
31ca0 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69   VFS, register i
31cb0 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20  t again.** with 
31cc0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
31cd0 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64  g set.  If two d
31ce0 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77  ifferent VFSes w
31cf0 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20  ith the.** same 
31d00 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65  name are registe
31d10 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f  red, the behavio
31d20 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  r is undefined. 
31d30 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20   If a.** VFS is 
31d40 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
31d50 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e  a name that is N
31d60 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
31d70 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20  string,.** then 
31d80 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
31d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31da0 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46   Unregister a VF
31db0 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
31dc0 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
31dd0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
31de0 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74  * If the default
31df0 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74   VFS is unregist
31e00 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46  ered, another VF
31e10 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a  S is chosen as.*
31e20 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20  * the default.  
31e30 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74  The choice for t
31e40 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72  he new VFS is ar
31e50 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52  bitrary..**.** R
31e60 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
31e70 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30 36  [H11203] [H11206
31e80 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31 32  ] [H11209] [H112
31e90 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48 31  12] [H11215] [H1
31ea0 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  1218].*/.sqlite3
31eb0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
31ec0 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
31ed0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
31ee0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
31ef0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
31f00 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
31f10 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
31f20 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
31f30 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
31f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
31f50 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d 20  utexes {H17000} 
31f60 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
31f70 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
31f80 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
31f90 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
31fa0 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
31fb0 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72  . Though they ar
31fc0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
31fd0 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
31fe0 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
31ff0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
32000 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
32010 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
32020 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
32030 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
32040 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
32050 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
32060 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
32070 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73  tions.** of thes
32080 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
32090 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
320a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
320b0 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
320c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
320d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
320e0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
320f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32100 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
32110 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
32120 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
32130 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
32140 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
32150 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
32160 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
32170 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
32180 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
32190 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
321a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
321b0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e  e SQLITE_MUTEX_N
321c0 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  OOP implementati
321d0 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72  on is a set of r
321e0 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20  outines.** that 
321f0 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
32200 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
32210 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
32220 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74  in.** a single-t
32230 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
32240 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ion.  The SQLITE
32250 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
32260 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
32270 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
32280 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
32290 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
322a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
322b0 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
322c0 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
322d0 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
322e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
322f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
32300 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
32310 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
32320 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
32330 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
32340 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
32350 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
32360 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
32370 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
32380 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20  ibrary. In this 
32390 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c  case the.** appl
323a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
323b0 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74  ply a custom mut
323c0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
323d0 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  n using the.** [
323e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
323f0 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74  TEX] option of t
32400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
32410 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  g() function.** 
32420 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73  before calling s
32430 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
32440 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72  e() or any other
32450 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
32460 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
32470 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  t calls sqlite3_
32480 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
32490 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 65  .** {H17011} The
324a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
324b0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
324c0 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
324d0 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
324e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
324f0 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 66   it. {H17012} If
32500 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
32510 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74  .** that means t
32520 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c  hat a mutex coul
32530 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  d not be allocat
32540 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 4c  ed. {H17013} SQL
32550 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69  ite.** will unwi
32560 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64  nd its stack and
32570 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
32580 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20 61  . {H17014} The a
32590 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
325a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
325b0 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  c() is one of th
325c0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
325d0 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tants:.**.** <ul
325e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
325f0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
32600 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
32610 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
32620 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
32630 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
32640 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
32650 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
32660 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  M.** <li>  SQLIT
32670 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
32680 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  EM2.** <li>  SQL
32690 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
326a0 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _PRNG.** <li>  S
326b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
326c0 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_LRU.** <li>  
326d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
326e0 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c  TIC_LRU2.** </ul
326f0 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d  >.**.** {H17015}
32700 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63   The first two c
32710 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73  onstants cause s
32720 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
32730 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a  oc() to create.*
32740 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20  * a new mutex.  
32750 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73  The new mutex is
32760 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20   recursive when 
32770 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
32780 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65  URSIVE.** is use
32790 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73  d but not necess
327a0 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51  arily so when SQ
327b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
327c0 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a  is used. {END}.*
327d0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
327e0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
327f0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
32800 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
32810 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
32820 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
32830 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
32840 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
32850 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
32860 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74 20  .  {H17016} But 
32870 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
32880 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72   request a recur
32890 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a  sive mutex in.**
328a0 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20   cases where it 
328b0 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65  really needs one
328c0 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61  .  {END} If a fa
328d0 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69  ster non-recursi
328e0 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  ve mutex.** impl
328f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76  ementation is av
32900 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68  ailable on the h
32910 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68  ost platform, th
32920 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65  e mutex subsyste
32930 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72  m.** might retur
32940 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69  n such a mutex i
32950 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51  n response to SQ
32960 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e  LITE_MUTEX_FAST.
32970 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20  .**.** {H17017} 
32980 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65  The other allowe
32990 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  d parameters to 
329a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
329b0 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72  loc() each retur
329c0 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
329d0 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
329e0 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45  isting mutex. {E
329f0 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63  ND}  Four static
32a00 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20   mutexes are.** 
32a10 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72  used by the curr
32a20 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  ent version of S
32a30 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76  QLite.  Future v
32a40 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
32a50 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64  e.** may add add
32a60 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d  itional static m
32a70 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20  utexes.  Static 
32a80 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20  mutexes are for 
32a90 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
32aa0 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20  by SQLite only. 
32ab0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
32ac0 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75  at use SQLite mu
32ad0 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  texes should.** 
32ae0 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e  use only the dyn
32af0 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74  amic mutexes ret
32b00 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f  urned by SQLITE_
32b10 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a  MUTEX_FAST or.**
32b20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
32b30 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b  CURSIVE..**.** {
32b40 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61  H17018} Note tha
32b50 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20  t if one of the 
32b60 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61  dynamic mutex pa
32b70 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45  rameters (SQLITE
32b80 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f  _MUTEX_FAST.** o
32b90 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  r SQLITE_MUTEX_R
32ba0 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65  ECURSIVE) is use
32bb0 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  d then sqlite3_m
32bc0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20  utex_alloc().** 
32bd0 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72  returns a differ
32be0 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65  ent mutex on eve
32bf0 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33  ry call.  {H1703
32c00 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73  4} But for the s
32c10 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74  tatic.** mutex t
32c20 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d  ypes, the same m
32c30 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64  utex is returned
32c40 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74   on every call t
32c50 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73  hat has.** the s
32c60 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e  ame type number.
32c70 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20  .**.** {H17019} 
32c80 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
32c90 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  x_free() routine
32ca0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70   deallocates a p
32cb0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c  reviously.** all
32cc0 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d  ocated dynamic m
32cd0 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53  utex. {H17020} S
32ce0 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
32cf0 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
32d00 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
32d10 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
32d20 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31  locates. {A17021
32d30 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  } The dynamic mu
32d40 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
32d50 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
32d60 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
32d70 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20  cated. {A17022} 
32d80 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
32d90 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
32da0 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
32db0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
32dc0 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32  behavior. {H1702
32dd0 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  3} SQLite never 
32de0 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61  deallocates.** a
32df0 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b   static mutex. {
32e00 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  END}.**.** The s
32e10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
32e20 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  er() and sqlite3
32e30 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75  _mutex_try() rou
32e40 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a  tines attempt.**
32e50 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65   to enter a mute
32e60 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61  x. {H17024} If a
32e70 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73  nother thread is
32e80 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20   already within 
32e90 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71  the mutex,.** sq
32ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
32eb0 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61  r() will block a
32ec0 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
32ed0 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75  _try() will retu
32ee0 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  rn.** SQLITE_BUS
32ef0 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65  Y. {H17025}  The
32f00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
32f10 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
32f20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
32f30 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
32f40 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48  ssful entry.  {H
32f50 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63  17026} Mutexes c
32f60 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
32f70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
32f80 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e  URSIVE can be en
32f90 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
32fa0 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
32fb0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37   thread..** {H17
32fc0 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73  027} In such cas
32fd0 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
32fe0 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
32ff0 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
33000 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
33010 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
33020 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41  * can enter.  {A
33030 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 61  17028} If the sa
33040 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20  me thread tries 
33050 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68  to enter any oth
33060 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75  er.** kind of mu
33070 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  tex more than on
33080 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ce, the behavior
33090 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
330a0 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74  * {H17029} SQLit
330b0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68  e will never exh
330c0 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68  ibit.** such beh
330d0 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e  avior in its own
330e0 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e   use of mutexes.
330f0 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74  .**.** Some syst
33100 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ems (for example
33110 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f  , Windows 95) do
33120 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
33130 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d   operation.** im
33140 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c  plemented by sql
33150 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
33160 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
33170 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
33180 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c  ex_try().** will
33190 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
331a0 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31  QLITE_BUSY.  {H1
331b0 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65  7030} The SQLite
331c0 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20   core only ever 
331d0 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  uses.** sqlite3_
331e0 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61  mutex_try() as a
331f0 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73  n optimization s
33200 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74  o this is accept
33210 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a  able behavior..*
33220 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68  *.** {H17031} Th
33230 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
33240 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20  leave() routine 
33250 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68  exits a mutex th
33260 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  at was.** previo
33270 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  usly entered by 
33280 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
33290 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62    {A17032} The b
332a0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
332b0 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
332c0 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
332d0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
332e0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
332f0 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
33300 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
33310 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20  ated.  {H17033} 
33320 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e  SQLite will.** n
33330 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20  ever do either. 
33340 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
33350 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
33360 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
33370 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75  er(), sqlite3_mu
33380 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a  tex_try(), or.**
33390 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
333a0 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c  eave() is a NULL
333b0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61   pointer, then a
333c0 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  ll three routine
333d0 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e  s.** behave as n
333e0 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  o-ops..**.** See
333f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
33400 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
33410 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
33420 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
33430 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
33440 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
33450 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
33460 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
33470 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
33480 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
33490 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
334a0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
334b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
334c0 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
334d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
334e0 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
334f0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
33500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
33510 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  tex Methods Obje
33520 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30  ct {H17120} <S20
33530 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  130>.** EXPERIME
33540 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  NTAL.**.** An in
33550 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
33560 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
33570 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
33580 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
33590 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
335a0 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
335b0 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
335c0 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
335d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
335e0 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
335f0 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
33600 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
33610 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
33620 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
33630 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
33640 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
33650 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
33660 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
33670 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
33680 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
33690 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
336a0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
336b0 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
336c0 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
336d0 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
336e0 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
336f0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
33700 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
33710 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
33720 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
33730 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
33740 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
33750 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
33760 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
33770 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
33780 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
33790 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
337a0 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
337b0 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
337c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
337d0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
337e0 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
337f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
33800 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
33810 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
33820 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66  xInit method def
33830 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
33840 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
33850 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
33860 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a  system initializ
33870 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c  ation by the sql
33880 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
33890 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b  ) function..** {
338a0 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74  H17001} The xMut
338b0 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73  exInit routine s
338c0 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  hall be called b
338d0 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f  y SQLite once fo
338e0 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74  r each.** effect
338f0 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ive call to [sql
33900 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
33910 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  )]..**.** The xM
33920 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64  utexEnd method d
33930 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
33940 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
33950 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
33960 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77  f system shutdow
33970 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  n by the sqlite3
33980 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63  _shutdown() func
33990 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70  tion. The.** imp
339a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
339b0 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78  his method is ex
339c0 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73  pected to releas
339d0 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e  e all outstandin
339e0 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f  g.** resources o
339f0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d  btained by the m
33a00 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70  utex methods imp
33a10 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70  lementation, esp
33a20 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65  ecially.** those
33a30 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65   obtained by the
33a40 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
33a50 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65  od. {H17003} The
33a60 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20   xMutexEnd().** 
33a70 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
33a80 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  be invoked once 
33a90 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  for each call to
33aa0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
33ab0 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  wn()]..**.** The
33ac0 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e   remaining seven
33ad0 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
33ae0 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
33af0 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c  re (xMutexAlloc,
33b00 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20  .** xMutexFree, 
33b10 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75  xMutexEnter, xMu
33b20 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65  texTry, xMutexLe
33b30 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20  ave, xMutexHeld 
33b40 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74  and.** xMutexNot
33b50 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20  held) implement 
33b60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
33b70 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63  terfaces (respec
33b80 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c  tively):.**.** <
33b90 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  ul>.**   <li>  [
33ba0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
33bb0 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  loc()] </li>.** 
33bc0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
33bd0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c  _mutex_free()] <
33be0 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
33bf0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
33c00 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  nter()] </li>.**
33c10 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
33c20 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c  3_mutex_try()] <
33c30 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
33c40 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
33c50 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  eave()] </li>.**
33c60 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
33c70 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
33c80 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
33c90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
33ca0 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  notheld()] </li>
33cb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33cc0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
33cd0 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20  nce is that the 
33ce0 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58  public sqlite3_X
33cf0 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75  XX functions enu
33d00 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65  merated.** above
33d10 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
33d20 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73   any invocations
33d30 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c   that pass a NUL
33d40 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
33d50 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20  d.** of a valid 
33d60 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68  mutex handle. Th
33d70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33d80 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73  s of the methods
33d90 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74   defined.** by t
33da0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72  his structure ar
33db0 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  e not required t
33dc0 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61  o handle this ca
33dd0 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a  se, the results.
33de0 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20  ** of passing a 
33df0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
33e00 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20  tead of a valid 
33e10 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65  mutex handle are
33e20 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69   undefined.** (i
33e30 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74  .e. it is accept
33e40 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20  able to provide 
33e50 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
33e60 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73  n that segfaults
33e70 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73   if.** it is pas
33e80 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  sed a NULL point
33e90 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  er)..*/.typedef 
33ea0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
33eb0 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c  utex_methods sql
33ec0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
33ed0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
33ee0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
33ef0 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65   {.  int (*xMute
33f00 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20 20  xInit)(void);.  
33f10 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64 29  int (*xMutexEnd)
33f20 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74 65  (void);.  sqlite
33f30 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 65  3_mutex *(*xMute
33f40 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20  xAlloc)(int);.  
33f50 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72 65  void (*xMutexFre
33f60 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e)(sqlite3_mutex
33f70 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d   *);.  void (*xM
33f80 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69 74  utexEnter)(sqlit
33f90 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69  e3_mutex *);.  i
33fa0 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29 28  nt (*xMutexTry)(
33fb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
33fc0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
33fd0 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33 5f  xLeave)(sqlite3_
33fe0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20  mutex *);.  int 
33ff0 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73 71  (*xMutexHeld)(sq
34000 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
34010 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f    int (*xMutexNo
34020 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d  theld)(sqlite3_m
34030 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a  utex *);.};../*.
34040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
34050 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e 20  ex Verification 
34060 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 38 30  Routines {H17080
34070 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 30 38  } <S20130> <S308
34080 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
34090 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
340a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
340b0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72  utex_notheld() r
340c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69  outines.** are i
340d0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
340e0 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29 20  inside assert() 
340f0 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31 37  statements. {H17
34100 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20  081} The SQLite 
34110 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73  core.** never us
34120 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
34130 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20  s except inside 
34140 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20  an assert() and 
34150 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
34160 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66  are advised to f
34170 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f  ollow the lead o
34180 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b 48 31  f the core.  {H1
34190 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 20 6f  7082} The core o
341a0 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  nly.** provides 
341b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
341c0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
341d0 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  es when it is co
341e0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74  mpiled.** with t
341f0 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he SQLITE_DEBUG 
34200 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 7d 20  flag.  {A17087} 
34210 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  External mutex i
34220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
34230 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69  * are only requi
34240 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74  red to provide t
34250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66  hese routines if
34260 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73   SQLITE_DEBUG is
34270 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20  .** defined and 
34280 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74  if NDEBUG is not
34290 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
342a0 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 20 72  {H17083} These r
342b0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72  outines should r
342c0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
342d0 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72  e mutex in their
342e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
342f0 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64  held or not held
34300 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20  , respectively, 
34310 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  by the calling t
34320 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31  hread..**.** {X1
34330 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d  7084} The implem
34340 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  entation is not 
34350 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
34360 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66  ided versions of
34370 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
34380 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79  es that actually
34390 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d   work. If the im
343a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
343b0 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f  s not provide wo
343c0 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e  rking.** version
343d0 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  s of these routi
343e0 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61  nes, it should a
343f0 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20  t least provide 
34400 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61 79  stubs that alway
34410 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65  s.** return true
34420 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65   so that one doe
34430 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f  s not get spurio
34440 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69  us assertion fai
34450 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lures..**.** {H1
34460 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72 67  7085} If the arg
34470 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
34480 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73  _mutex_held() is
34490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
344a0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74  then.** the rout
344b0 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ine should retur
344c0 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73  n 1.  {END} This
344d0 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69   seems counter-i
344e0 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a  ntuitive since.*
344f0 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75  * clearly the mu
34500 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65  tex cannot be he
34510 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f  ld if it does no
34520 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68  t exist.  But th
34530 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20  e.** the reason 
34540 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e  the mutex does n
34550 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61  ot exist is beca
34560 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73  use the build is
34570 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75   not.** using mu
34580 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64  texes.  And we d
34590 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61  o not want the a
345a0 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69  ssert() containi
345b0 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74  ng the.** call t
345c0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
345d0 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20  held() to fail, 
345e0 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  so a non-zero re
345f0 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61  turn is.** the a
34600 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67  ppropriate thing
34610 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38 36   to do.  {H17086
34620 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
34630 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a  tex_notheld().**
34640 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
34650 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20  d also return 1 
34660 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c  when given a NUL
34670 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e  L pointer..*/.in
34680 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
34690 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
346a0 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
346b0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
346c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
346d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
346e0 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b 48  : Mutex Types {H
346f0 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e 0a  17001} <H17000>.
34700 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
34710 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
34720 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65  ] interface take
34730 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
34740 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ent.** which is 
34750 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
34760 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  eger constants..
34770 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66  **.** The set of
34780 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
34790 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20  may change from 
347a0 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61  one SQLite relea
347b0 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  se to the.** nex
347c0 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
347d0 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20 74   that override t
347e0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65  he built-in mute
347f0 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a  x logic must be.
34800 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20 61  ** prepared to a
34810 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74  ccommodate addit
34820 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74  ional static mut
34830 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  exes..*/.#define
34840 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
34850 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30  ST             0
34860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34870 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
34880 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
34890 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
348a0 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32  ATIC_MASTER    2
348b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
348c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
348d0 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c         3  /* sql
348e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f  ite3_malloc() */
348f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34900 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
34910 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54  2      4  /* NOT
34920 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65   USED */.#define
34930 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34940 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34  ATIC_OPEN      4
34950 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65    /* sqlite3Btre
34960 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69  eOpen() */.#defi
34970 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
34980 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20  STATIC_PRNG     
34990 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72   5  /* sqlite3_r
349a0 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69  andom() */.#defi
349b0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
349c0 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20  STATIC_LRU      
349d0 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   6  /* lru page 
349e0 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  list */.#define 
349f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
34a00 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20  TIC_LRU2      7 
34a10 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73   /* lru page lis
34a20 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
34a30 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20 74  3REF: Retrieve t
34a40 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20 64  he mutex for a d
34a50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34a60 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31 37  on {H17002} <H17
34a70 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  000>.**.** This 
34a80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34a90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20  s a pointer the 
34aa0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
34ab0 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20  object that .** 
34ac0 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73  serializes acces
34ad0 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  s to the [databa
34ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67  se connection] g
34af0 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75  iven in the argu
34b00 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ment.** when the
34b10 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
34b20 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] is Serialized.
34b30 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72 65  .** If the [thre
34b40 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53  ading mode] is S
34b50 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72 20  ingle-thread or 
34b60 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68 65  Multi-thread the
34b70 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  n this.** routin
34b80 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
34b90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
34ba0 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69  ite3_mutex *sqli
34bb0 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71 6c  te3_db_mutex(sql
34bc0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
34bd0 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76  API3REF: Low-Lev
34be0 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61  el Control Of Da
34bf0 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48 31  tabase Files {H1
34c00 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a  1300} <S30800>.*
34c10 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54 68  *.** {H11301} Th
34c20 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
34c30 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
34c40 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
34c50 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
34c60 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
34c70 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
34c80 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
34c90 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
34ca0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
34cb0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
34cc0 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
34cd0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
34ce0 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d 20  ument. {H11302} 
34cf0 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  The.** name of t
34d00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74  he database is t
34d10 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
34d20 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
34d30 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   by the.** <a hr
34d40 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e  ef="lang_attach.
34d50 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e  html">ATTACH</a>
34d60 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61   SQL command tha
34d70 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20  t opened the.** 
34d80 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33 30  database. {H1130
34d90 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68  3} To control th
34da0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
34db0 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61  file, use the na
34dc0 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20  me "main".** or 
34dd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
34de0 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68 69  {H11304} The thi
34df0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
34e00 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
34e10 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20   routine.** are 
34e20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20  passed directly 
34e30 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73  through to the s
34e40 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
34e50 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a  parameters of.**
34e60 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
34e70 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31 33  l method.  {H113
34e80 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
34e90 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c  alue of the xFil
34ea0 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68  eControl.** meth
34eb0 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72  od becomes the r
34ec0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
34ed0 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
34ee0 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20 74  ** {H11306} If t
34ef0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34f00 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
34f10 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
34f20 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
34f30 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
34f40 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
34f50 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
34f60 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69 73  d. {H11307} This
34f70 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
34f80 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
34f90 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
34fa0 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
34fb0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
34fc0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
34fd0 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31 33  errmsg()]. {A113
34fe0 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 69  08} The underlyi
34ff0 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ng xFileControl 
35000 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20  method might.** 
35010 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49  also return SQLI
35020 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31 33  TE_ERROR.  {A113
35030 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 20  09} There is no 
35040 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69  way to distingui
35050 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e  sh between.** an
35060 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61   incorrect zDbNa
35070 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45  me and an SQLITE
35080 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72  _ERROR return fr
35090 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  om the underlyin
350a0 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  g.** xFileContro
350b0 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a  l method. {END}.
350c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
350d0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
350e0 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20  CKSTATE].*/.int 
350f0 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
35100 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63  trol(sqlite3*, c
35110 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
35120 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  me, int op, void
35130 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35140 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74  REF: Testing Int
35150 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d 20  erface {H11400} 
35160 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
35170 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  he sqlite3_test_
35180 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 66  control() interf
35190 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ace is used to r
351a0 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c  ead out internal
351b0 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51 4c  .** state of SQL
351c0 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63  ite and to injec
351d0 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 51  t faults into SQ
351e0 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e 67  Lite for testing
351f0 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 54  .** purposes.  T
35200 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
35210 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74 69  er is an operati
35220 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65 74  on code that det
35230 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e  ermines.** the n
35240 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20  umber, meaning, 
35250 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  and operation of
35260 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
35270 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a  parameters..**.*
35280 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
35290 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65 20   is not for use 
352a0 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e  by applications.
352b0 20 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c 65    It exists sole
352c0 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66 79  ly.** for verify
352d0 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74 20  ing the correct 
352e0 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
352f0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
35300 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f    Depending.** o
35310 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65  n how the SQLite
35320 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d 70   library is comp
35330 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65 72  iled, this inter
35340 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20 65  face might not e
35350 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  xist..**.** The 
35360 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 6f  details of the o
35370 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20  peration codes, 
35380 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20  their meanings, 
35390 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  the parameters.*
353a0 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e 64  * they take, and
353b0 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 61 72   what they do ar
353c0 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f  e all subject to
353d0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
353e0 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b  notice..** Unlik
353f0 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53 51  e most of the SQ
35400 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 20 66  Lite API, this f
35410 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
35420 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20  uaranteed to.** 
35430 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74 65  operate consiste
35440 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65  ntly from one re
35450 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
35460 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
35470 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 69  3_test_control(i
35480 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
35490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
354a0 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20  sting Interface 
354b0 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73 20  Operation Codes 
354c0 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30 30  {H11410} <H11400
354d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  >.**.** These co
354e0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
354f0 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20  valid operation 
35500 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20  code parameters 
35510 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66  used.** as the f
35520 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
35530 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63   [sqlite3_test_c
35540 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ontrol()]..**.**
35550 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   These parameter
35560 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e  s and their mean
35570 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63 74  ings are subject
35580 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69   to change.** wi
35590 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54  thout notice.  T
355a0 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20  hese values are 
355b0 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70  for testing purp
355c0 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70  oses only..** Ap
355d0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
355e0 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66  d not use any of
355f0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
35600 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s or the.** [sql
35610 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
35620 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  l()] interface..
35630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35640 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f  E_TESTCTRL_PRNG_
35650 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SAVE            
35660 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
35670 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52  LITE_TESTCTRL_PR
35680 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20  NG_RESTORE      
35690 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
356a0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
356b0 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20  _PRNG_RESET     
356c0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
356d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
356e0 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20  TRL_BITVEC_TEST 
356f0 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23               8.#
35700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
35710 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53  STCTRL_FAULT_INS
35720 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  TALL            
35730 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
35740 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e  _TESTCTRL_BENIGN
35750 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20  _MALLOC_HOOKS   
35760 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
35770 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e  ITE_TESTCTRL_PEN
35780 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20  DING_BYTE       
35790 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
357a0 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20  API3REF: SQLite 
357b0 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20 7b  Runtime Status {
357c0 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30 3e  H17200} <S60200>
357d0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
357e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
357f0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
35800 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d   retrieve runtim
35810 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61  e status informa
35820 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68  tion.** about th
35830 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66  e preformance of
35840 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74   SQLite, and opt
35850 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74  ionally to reset
35860 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68   various.** high
35870 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 68  water marks.  Th
35880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35890 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
358a0 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ode for.** the s
358b0 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 65  pecific paramete
358c0 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 52  r to measure.  R
358d0 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 65  ecognized intege
358e0 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f  r codes.** are o
358f0 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49  f the form [SQLI
35900 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59  TE_STATUS_MEMORY
35910 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f 53  _USED | SQLITE_S
35920 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54  TATUS_...]..** T
35930 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
35940 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
35950 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e  r is returned in
35960 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a  to *pCurrent..**
35970 20 54 68 65 20 68 69 67 68 65 73 74 20 72 65 63   The highest rec
35980 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20 72  orded value is r
35990 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67  eturned in *pHig
359a0 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 65 0a  hwater.  If the.
359b0 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73 20  ** resetFlag is 
359c0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68  true, then the h
359d0 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76 61  ighest record va
359e0 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66 74  lue is reset aft
359f0 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65  er.** *pHighwate
35a00 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53 6f  r is written. So
35a10 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 64 6f  me parameters do
35a20 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65 20   not record the 
35a30 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 65  highest.** value
35a40 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61 72  .  For those par
35a50 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 69  ameters.** nothi
35a60 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ng is written in
35a70 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20 61  to *pHighwater a
35a80 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c 61 67  nd the resetFlag
35a90 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20   is ignored..** 
35aa0 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 73  Other parameters
35ab0 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65   record only the
35ac0 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20   highwater mark 
35ad0 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72  and not the curr
35ae0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46  ent.** value.  F
35af0 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72 20  or these latter 
35b00 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69  parameters nothi
35b10 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ng is written in
35b20 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a  to *pCurrent..**
35b30 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35b40 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
35b50 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  OK on success an
35b60 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20  d a non-zero.** 
35b70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
35b80 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  failure..**.** T
35b90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
35ba0 68 72 65 61 64 73 61 66 65 20 62 75 74 20 69 73  hreadsafe but is
35bb0 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 68   not atomic.  Th
35bc0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a 2a  is routine can.*
35bd0 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 6f  * called while o
35be0 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72 65  ther threads are
35bf0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 6d   running the sam
35c00 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20 53  e or different S
35c10 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61  QLite.** interfa
35c20 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74 68  ces.  However th
35c30 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
35c40 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 61  d in *pCurrent a
35c50 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65  nd.** *pHighwate
35c60 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73 74  r reflect the st
35c70 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20 61  atus of SQLite a
35c80 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69 6e  t different poin
35c90 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e  ts in time.** an
35ca0 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  d it is possible
35cb0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
35cc0 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e 67  read might chang
35cd0 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  e the parameter.
35ce0 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  ** in between th
35cf0 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 43  e times when *pC
35d00 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 67  urrent and *pHig
35d10 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74 74  hwater are writt
35d20 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  en..**.** See al
35d30 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  so: [sqlite3_db_
35d40 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c  status()].*/.SQL
35d50 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
35d60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 61   int sqlite3_sta
35d70 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 20  tus(int op, int 
35d80 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 2a  *pCurrent, int *
35d90 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 20  pHighwater, int 
35da0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f 2a  resetFlag);.../*
35db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
35dc0 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20  atus Parameters 
35dd0 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 30  {H17250} <H17200
35de0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
35df0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  L.**.** These in
35e00 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
35e10 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f 75  designate variou
35e20 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 75  s run-time statu
35e30 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  s parameters.** 
35e40 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 75  that can be retu
35e50 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
35e60 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a  _status()]..**.*
35e70 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
35e80 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f  LITE_STATUS_MEMO
35e90 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20  RY_USED</dt>.** 
35ea0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
35eb0 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65 6e  er is the curren
35ec0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  t amount of memo
35ed0 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a 2a  ry checked out.*
35ee0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
35ef0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 68  _malloc()], eith
35f00 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 69  er directly or i
35f10 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 0a  ndirectly.  The.
35f20 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 64  ** figure includ
35f30 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 6f  es calls made to
35f40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35f50 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c 69  ()] by the appli
35f60 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 6e  cation.** and in
35f70 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 73  ternal memory us
35f80 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 74  age by the SQLit
35f90 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 61  e library.  Scra
35fa0 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  tch memory.** co
35fb0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c  ntrolled by [SQL
35fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
35fd0 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 72  CH] and auxiliar
35fe0 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a 20  y page-cache.** 
35ff0 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c 65  memory controlle
36000 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d by [SQLITE_CON
36010 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 69  FIG_PAGECACHE] i
36020 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
36030 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d 65  n.** this parame
36040 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e 74  ter.  The amount
36050 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
36060 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c 6f   sum of the allo
36070 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 20  cation.** sizes 
36080 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 74  as reported by t
36090 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 20  he xSize method 
360a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  in [sqlite3_mem_
360b0 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a 2a  methods].</dd>.*
360c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
360d0 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49  STATUS_MALLOC_SI
360e0 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ZE</dt>.** <dd>T
360f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65  his parameter re
36100 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73  cords the larges
36110 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
36120 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68  ion request.** h
36130 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  anded to [sqlite
36140 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
36150 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
36160 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a 20  )] (or their.** 
36170 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 6c  internal equival
36180 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 65  ents).  Only the
36190 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
361a0 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68  in the.** *pHigh
361b0 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20  water parameter 
361c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  to [sqlite3_stat
361d0 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65  us()] is of inte
361e0 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76  rest.  .** The v
361f0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74  alue written int
36200 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20  o the *pCurrent 
36210 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64  parameter is und
36220 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
36230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54  ** <dt>SQLITE_ST
36240 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55  ATUS_PAGECACHE_U
36250 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  SED</dt>.** <dd>
36260 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72  This parameter r
36270 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
36280 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 20  r of pages used 
36290 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  out of the.** [p
362a0 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  agecache memory 
362b0 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 20  allocator] that 
362c0 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75  was configured u
362d0 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  sing .** [SQLITE
362e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
362f0 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c 75  E].  The.** valu
36300 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e  e returned is in
36310 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 62   pages, not in b
36320 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ytes.</dd>.**.**
36330 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54   <dt>SQLITE_STAT
36340 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45  US_PAGECACHE_OVE
36350 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RFLOW</dt>.** <d
36360 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72  d>This parameter
36370 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
36380 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
36390 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 6c  page cache.** al
363a0 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63  location which c
363b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74  ould not be stat
363c0 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53  isfied by the [S
363d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
363e0 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 65  ECACHE].** buffe
363f0 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63  r and where forc
36400 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74  ed to overflow t
36410 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
36420 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 65  c()].  The.** re
36430 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e 63  turned value inc
36440 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f 6e  ludes allocation
36450 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65  s that overflowe
36460 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a 2a  d because they.*
36470 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 67  * where too larg
36480 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 72  e (they were lar
36490 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 7a  ger than the "sz
364a0 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  " parameter to.*
364b0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
364c0 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e 64  _PAGECACHE]) and
364d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61   allocations tha
364e0 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63  t overflowed bec
364f0 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 65  ause.** no space
36500 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 65   was left in the
36510 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 64   page cache.</dd
36520 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36530 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
36540 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a  CHE_SIZE</dt>.**
36550 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
36560 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20  ter records the 
36570 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61  largest memory a
36580 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
36590 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b  t.** handed to [
365a0 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79  pagecache memory
365b0 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e   allocator].  On
365c0 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ly the value ret
365d0 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  urned in the.** 
365e0 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61  *pHighwater para
365f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
36600 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f  3_status()] is o
36610 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a  f interest.  .**
36620 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74   The value writt
36630 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75  en into the *pCu
36640 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20  rrent parameter 
36650 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  is undefined.</d
36660 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
36670 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
36680 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20  CH_USED</dt>.** 
36690 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
366a0 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  er returns the n
366b0 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 74  umber of allocat
366c0 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f 66  ions used out of
366d0 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 68   the.** [scratch
366e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
366f0 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73  r] configured us
36700 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ing.** [SQLITE_C
36710 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e 20  ONFIG_SCRATCH]. 
36720 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
36730 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 61  ned is in alloca
36740 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 6e  tions, not.** in
36750 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 61   bytes.  Since a
36760 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 6d   single thread m
36770 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e 65  ay only have one
36780 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
36790 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  ion.** outstandi
367a0 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 73  ng at time, this
367b0 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f 20   parameter also 
367c0 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62  reports the numb
367d0 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a 2a  er of threads.**
367e0 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 6d   using scratch m
367f0 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 6d  emory at the sam
36800 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e time.</dd>.**.
36810 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54  ** <dt>SQLITE_ST
36820 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45  ATUS_SCRATCH_OVE
36830 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RFLOW</dt>.** <d
36840 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72  d>This parameter
36850 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
36860 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
36870 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a  scratch memory.*
36880 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69  * allocation whi
36890 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ch could not be 
368a0 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68  statisfied by th
368b0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
368c0 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 66  _SCRATCH].** buf
368d0 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f  fer and where fo
368e0 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77  rced to overflow
368f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
36900 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 6c  loc()].  The val
36910 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ues.** returned 
36920 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f 77  include overflow
36930 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72 65  s because the re
36940 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69  quested allocati
36950 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c 61  on was too.** la
36960 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 62  rger (that is, b
36970 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 65  ecause the reque
36980 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  sted allocation 
36990 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20  was larger than 
369a0 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 61  the.** "sz" para
369b0 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 45  meter to [SQLITE
369c0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
369d0 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e 6f  ) and because no
369e0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 0a   scratch buffer.
369f0 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 76  ** slots were av
36a00 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 64  ailable..** </dd
36a10 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36a20 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
36a30 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  H_SIZE</dt>.** <
36a40 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
36a50 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  r records the la
36a60 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  rgest memory all
36a70 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a  ocation request.
36a80 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 63  ** handed to [sc
36a90 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
36aa0 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74  ocator].  Only t
36ab0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
36ac0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69  d in the.** *pHi
36ad0 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65  ghwater paramete
36ae0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  r to [sqlite3_st
36af0 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e  atus()] is of in
36b00 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65  terest.  .** The
36b10 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69   value written i
36b20 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e  nto the *pCurren
36b30 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  t parameter is u
36b40 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
36b50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
36b60 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54  STATUS_PARSER_ST
36b70 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ACK</dt>.** <dd>
36b80 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72  This parameter r
36b90 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 65  ecords the deepe
36ba0 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b 2e  st parser stack.
36bb0 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20    It is only.** 
36bc0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 51  meaningful if SQ
36bd0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
36be0 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d 41   with [YYTRACKMA
36bf0 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f 64  XSTACKDEPTH].</d
36c00 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  d>.** </dl>.**.*
36c10 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 72  * New status par
36c20 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 61  ameters may be a
36c30 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 74  dded from time t
36c40 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 69  o time..*/.#defi
36c50 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
36c60 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 20  _MEMORY_USED    
36c70 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
36c80 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
36c90 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 20  GECACHE_USED    
36ca0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
36cb0 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43  ITE_STATUS_PAGEC
36cc0 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 20  ACHE_OVERFLOW   
36cd0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
36ce0 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f  _STATUS_SCRATCH_
36cf0 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a 23  USED         3.#
36d00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
36d10 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45  ATUS_SCRATCH_OVE
36d20 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 66  RFLOW     4.#def
36d30 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
36d40 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 20  S_MALLOC_SIZE   
36d50 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
36d60 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50   SQLITE_STATUS_P
36d70 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 20  ARSER_STACK     
36d80 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
36d90 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45  LITE_STATUS_PAGE
36da0 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 20  CACHE_SIZE      
36db0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
36dc0 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
36dd0 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 0a  _SIZE         8.
36de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36df0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
36e00 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 37  tion Status {H17
36e10 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  500} <S60200>.**
36e20 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
36e30 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
36e40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ce is used to re
36e50 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73  trieve runtime s
36e60 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f  tatus informatio
36e70 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 69  n .** about a si
36e80 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20 63  ngle [database c
36e90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
36ea0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
36eb0 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  is the.** databa
36ec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62  se connection ob
36ed0 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72  ject to be inter
36ee0 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 65  rogated.  The se
36ef0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  cond argument.**
36f00 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
36f10 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 65  r to interrogate
36f20 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 68  .  Currently, th
36f30 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 76  e only allowed v
36f40 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20  alue.** for the 
36f50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
36f60 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 54   is [SQLITE_DBST
36f70 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55  ATUS_LOOKASIDE_U
36f80 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  SED]..** Additio
36f90 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c 6c  nal options will
36fa0 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20 69   likely appear i
36fb0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
36fc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
36fd0 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76  ** The current v
36fe0 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 75  alue of the requ
36ff0 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72 20  ested parameter 
37000 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
37010 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 65  *pCur.** and the
37020 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74   highest instant
37030 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 20  aneous value is 
37040 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48  written into *pH
37050 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  iwtr.  If.** the
37060 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 75   resetFlg is tru
37070 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 68  e, then the high
37080 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75  est instantaneou
37090 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 65  s value is.** re
370a0 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 6f  set back down to
370b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
370c0 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ue..**.** See al
370d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  so: [sqlite3_sta
370e0 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tus()] and [sqli
370f0 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28  te3_stmt_status(
37100 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  )]..*/.SQLITE_EX
37110 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
37120 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
37130 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
37140 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 69 6e  p, int *pCur, in
37150 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 20 72  t *pHiwtr, int r
37160 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a  esetFlg);../*.**
37170 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75   CAPI3REF: Statu
37180 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72  s Parameters for
37190 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
371a0 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d 20 3c  tions {H17520} <
371b0 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 45 52  H17500>.** EXPER
371c0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 53 74  IMENTAL.**.** St
371d0 61 74 75 73 20 76 65 72 62 73 20 66 6f 72 20 5b  atus verbs for [
371e0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
371f0 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  s()]..**.** <dl>
37200 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
37210 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44  BSTATUS_LOOKASID
37220 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_USED</dt>.** <
37230 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
37240 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
37250 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  mber of lookasid
37260 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 73 20 63  e memory slots c
37270 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 68 65 63  urrently.** chec
37280 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a 2a  ked out.</dd>.**
37290 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
372a0 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55  e SQLITE_DBSTATU
372b0 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44  S_LOOKASIDE_USED
372c0 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43       0.../*.** C
372d0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
372e0 64 20 53 74 61 74 65 6d 65 6e 74 20 53 74 61 74  d Statement Stat
372f0 75 73 20 7b 48 31 37 35 35 30 7d 20 3c 53 36 30  us {H17550} <S60
37300 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
37310 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  NTAL.**.** Each 
37320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37330 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 76 61 72  nt maintains var
37340 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ious.** [SQLITE_
37350 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20  STMTSTATUS_SORT 
37360 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 68 61 74  | counters] that
37370 20 6d 65 61 73 75 72 65 20 74 68 65 20 6e 75 6d   measure the num
37380 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d 65 73 20  ber.** of times 
37390 69 74 20 68 61 73 20 70 65 72 66 6f 72 6d 65 64  it has performed
373a0 20 73 70 65 63 69 66 69 63 20 6f 70 65 72 61 74   specific operat
373b0 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 63 6f 75  ions.  These cou
373c0 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 62 65 20  nters can.** be 
373d0 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 20  used to monitor 
373e0 74 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  the performance 
373f0 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
37400 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  of the prepared.
37410 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  ** statements.  
37420 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
37430 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61  the number of ta
37440 62 6c 65 20 73 74 65 70 73 20 67 72 65 61 74 6c  ble steps greatl
37450 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 74 68 65  y exceeds.** the
37460 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c 65   number of table
37470 20 73 65 61 72 63 68 65 73 20 6f 72 20 72 65 73   searches or res
37480 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 74 20 77  ult rows, that w
37490 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 69 6e 64  ould tend to ind
374a0 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 20 74 68  icate.** that th
374b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
374c0 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 20 61 20  ment is using a 
374d0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20  full table scan 
374e0 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 61  rather than.** a
374f0 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a 2a  n index.  .**.**
37500 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
37510 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  is used to retri
37520 65 76 65 20 61 6e 64 20 72 65 73 65 74 20 63 6f  eve and reset co
37530 75 6e 74 65 72 20 76 61 6c 75 65 73 20 66 72 6f  unter values fro
37540 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 72 65 64  m.** a [prepared
37550 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 54 68   statement].  Th
37560 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
37570 20 69 73 20 74 68 65 20 70 72 65 70 61 72 65 64   is the prepared
37580 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 62   statement.** ob
37590 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72  ject to be inter
375a0 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 65  rogated.  The se
375b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  cond argument.**
375c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
375d0 6f 64 65 20 66 6f 72 20 61 20 73 70 65 63 69 66  ode for a specif
375e0 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53  ic [SQLITE_STMTS
375f0 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75  TATUS_SORT | cou
37600 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 65 20 69  nter].** to be i
37610 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 0a 2a 2a  nterrogated. .**
37620 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   The current val
37630 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  ue of the reques
37640 74 65 64 20 63 6f 75 6e 74 65 72 20 69 73 20 72  ted counter is r
37650 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74  eturned..** If t
37660 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74  he resetFlg is t
37670 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
37680 75 6e 74 65 72 20 69 73 20 72 65 73 65 74 20 74  unter is reset t
37690 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 74 68 69  o zero after thi
376a0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63  s.** interface c
376b0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
376c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
376d0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20  lite3_status()] 
376e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  and [sqlite3_db_
376f0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51  status()]..*/.SQ
37700 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
37710 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  L int sqlite3_st
37720 6d 74 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65  mt_status(sqlite
37730 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 6f 70 2c  3_stmt*, int op,
37740 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a  int resetFlg);..
37750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37760 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72  Status Parameter
37770 73 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 73  s for prepared s
37780 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 37 35 37  tatements {H1757
37790 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 2a 20 45  0} <H17550>.** E
377a0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
377b0 2a 20 54 68 65 73 65 20 70 72 65 70 72 6f 63 65  * These preproce
377c0 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 65 66 69  ssor macros defi
377d0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
377e0 20 74 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e 74   that name count
377f0 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73 73  er.** values ass
37800 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37810 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73   [sqlite3_stmt_s
37820 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61  tatus()] interfa
37830 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69  ce..** The meani
37840 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
37850 75 73 20 63 6f 75 6e 74 65 72 73 20 61 72 65 20  us counters are 
37860 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
37870 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
37880 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f  LITE_STMTSTATUS_
37890 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 3c 2f 64  FULLSCAN_STEP</d
378a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69  t>.** <dd>This i
378b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
378c0 74 69 6d 65 73 20 74 68 61 74 20 53 51 4c 69 74  times that SQLit
378d0 65 20 68 61 73 20 73 74 65 70 70 65 64 20 66 6f  e has stepped fo
378e0 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 20 74 61  rward in.** a ta
378f0 62 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20 61  ble as part of a
37900 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
37910 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 65 72 73  .  Large numbers
37920 20 66 6f 72 20 74 68 69 73 20 63 6f 75 6e 74 65   for this counte
37930 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 63 61 74  r.** may indicat
37940 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 65 73 20  e opportunities 
37950 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  for performance 
37960 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 68 72 6f  improvement thro
37970 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 75 6c 20  ugh .** careful 
37980 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c  use of indices.<
37990 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
379a0 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53  QLITE_STMTSTATUS
379b0 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _SORT</dt>.** <d
379c0 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75  d>This is the nu
379d0 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 6f 70 65  mber of sort ope
379e0 72 61 74 69 6f 6e 73 20 74 68 61 74 20 68 61 76  rations that hav
379f0 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a 2a 20 41  e occurred..** A
37a00 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20   non-zero value 
37a10 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 65 72 20  in this counter 
37a20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 61 6e 20  may indicate an 
37a30 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 0a 2a  opportunity to.*
37a40 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 70 65  * improvement pe
37a50 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 6f 75 67  rformance throug
37a60 68 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66  h careful use of
37a70 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a   indices.</dd>.*
37a80 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
37a90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d  efine SQLITE_STM
37aa0 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e  TSTATUS_FULLSCAN
37ab0 5f 53 54 45 50 20 20 20 20 20 31 0a 23 64 65 66  _STEP     1.#def
37ac0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d 54 53  ine SQLITE_STMTS
37ad0 54 41 54 55 53 5f 53 4f 52 54 20 20 20 20 20 20  TATUS_SORT      
37ae0 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a          2../*.**
37af0 20 43 41 50 49 33 52 45 46 3a 20 43 75 73 74 6f   CAPI3REF: Custo
37b00 6d 20 50 61 67 65 20 43 61 63 68 65 20 4f 62 6a  m Page Cache Obj
37b10 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ect.** EXPERIMEN
37b20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
37b30 6c 69 74 65 33 5f 70 63 61 63 68 65 20 74 79 70  lite3_pcache typ
37b40 65 20 69 73 20 6f 70 61 71 75 65 2e 20 20 49 74  e is opaque.  It
37b50 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
37b60 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 67 67 61  by.** the plugga
37b70 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  ble module.  The
37b80 20 53 51 4c 69 74 65 20 63 6f 72 65 20 68 61 73   SQLite core has
37b90 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 20 6f 66   no knowledge of
37ba0 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 6f 72 20  .** its size or 
37bb0 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 63 74 75  internal structu
37bc0 72 65 20 61 6e 64 20 6e 65 76 65 72 20 64 65 61  re and never dea
37bd0 6c 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  ls with the.** s
37be0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 6f 62  qlite3_pcache ob
37bf0 6a 65 63 74 20 65 78 63 65 70 74 20 62 79 20 68  ject except by h
37c00 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 73 73 69  olding and passi
37c10 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 74  ng pointers.** t
37c20 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a  o the object..**
37c30 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 74 65 33  .** See [sqlite3
37c40 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
37c50 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
37c60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
37c70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
37c80 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 73 71  qlite3_pcache sq
37c90 6c 69 74 65 33 5f 70 63 61 63 68 65 3b 0a 0a 2f  lite3_pcache;../
37ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
37cb0 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 66 69 6e  pplication Defin
37cc0 65 64 20 50 61 67 65 20 43 61 63 68 65 2e 0a 2a  ed Page Cache..*
37cd0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
37ce0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
37cf0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
37d00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
37d10 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63 65  , ...) interface
37d20 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72   can.** register
37d30 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20   an alternative 
37d40 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
37d50 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 70 61 73  mentation by pas
37d60 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a 2a 20 69  sing in an .** i
37d70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
37d80 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
37d90 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 65 2e  thods structure.
37da0 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 20 6f 66   The majority of
37db0 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 20 6d 65   the .** heap me
37dc0 6d 6f 72 79 20 75 73 65 64 20 62 79 20 73 71 6c  mory used by sql
37dd0 69 74 65 20 69 73 20 75 73 65 64 20 62 79 20 74  ite is used by t
37de0 68 65 20 70 61 67 65 20 63 61 63 68 65 20 74 6f  he page cache to
37df0 20 63 61 63 68 65 20 64 61 74 61 20 72 65 61 64   cache data read
37e00 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 20 72 65   .** from, or re
37e10 61 64 79 20 74 6f 20 62 65 20 77 72 69 74 74 65  ady to be writte
37e20 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 61 62 61  n to, the databa
37e30 73 65 20 66 69 6c 65 2e 20 42 79 20 69 6d 70 6c  se file. By impl
37e40 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a 2a 20 63  ementing a .** c
37e50 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
37e60 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2c   using this API,
37e70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37e80 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d 6f 72 65  can control more
37e90 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c 79 20 74   .** precisely t
37ea0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  he amount of mem
37eb0 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 62 79 20  ory consumed by 
37ec0 73 71 6c 69 74 65 2c 20 74 68 65 20 77 61 79 20  sqlite, the way 
37ed0 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 73 61 69  in which .** sai
37ee0 64 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  d memory is allo
37ef0 63 61 74 65 64 20 61 6e 64 20 72 65 6c 65 61 73  cated and releas
37f00 65 64 2c 20 61 6e 64 20 74 68 65 20 70 6f 6c 69  ed, and the poli
37f10 63 69 65 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a  cies used to .**
37f20 20 64 65 74 65 72 6d 69 6e 65 20 65 78 61 63 74   determine exact
37f30 6c 79 20 77 68 69 63 68 20 70 61 72 74 73 20 6f  ly which parts o
37f40 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
37f50 65 20 61 72 65 20 63 61 63 68 65 64 20 61 6e 64  e are cached and
37f60 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 6c 6f 6e   for .** how lon
37f70 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  g..**.** The con
37f80 74 65 6e 74 73 20 6f 66 20 74 68 65 20 73 74 72  tents of the str
37f90 75 63 74 75 72 65 20 61 72 65 20 63 6f 70 69 65  ucture are copie
37fa0 64 20 74 6f 20 61 6e 20 69 6e 74 65 72 6e 61 6c  d to an internal
37fb0 20 62 75 66 66 65 72 20 62 79 20 73 71 6c 69 74   buffer by sqlit
37fc0 65 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  e.** within the 
37fd0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37fe0 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a 0a 2a 2a 20  _config]..**.** 
37ff0 54 68 65 20 78 49 6e 69 74 28 29 20 6d 65 74 68  The xInit() meth
38000 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 63  od is called onc
38010 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20  e for each call 
38020 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  to [sqlite3_init
38030 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 28 75 73  ialize()].** (us
38040 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65 20  ually only once 
38050 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
38060 69 6d 65 20 6f 66 20 74 68 65 20 70 72 6f 63 65  ime of the proce
38070 73 73 29 2e 20 49 74 20 69 73 20 70 61 73 73 65  ss). It is passe
38080 64 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  d.** a copy of t
38090 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  he sqlite3_pcach
380a0 65 5f 6d 65 74 68 6f 64 73 2e 70 41 72 67 20 76  e_methods.pArg v
380b0 61 6c 75 65 2e 20 49 74 20 63 61 6e 20 62 65 20  alue. It can be 
380c0 75 73 65 64 20 74 6f 20 73 65 74 0a 2a 2a 20 75  used to set.** u
380d0 70 20 67 6c 6f 62 61 6c 20 73 74 72 75 63 74 75  p global structu
380e0 72 65 73 20 61 6e 64 20 6d 75 74 65 78 65 73 20  res and mutexes 
380f0 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20  required by the 
38100 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
38110 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  e .** implementa
38120 74 69 6f 6e 2e 20 54 68 65 20 78 53 68 75 74 64  tion. The xShutd
38130 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 69 73 20  own() method is 
38140 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
38150 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  in .** [sqlite3_
38160 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 69 66 20  shutdown()], if 
38170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
38180 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 41 50 49  invokes this API
38190 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 64  . It can be used
381a0 0a 2a 2a 20 74 6f 20 63 6c 65 61 6e 20 75 70 20  .** to clean up 
381b0 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  any outstanding 
381c0 72 65 73 6f 75 72 63 65 73 20 62 65 66 6f 72 65  resources before
381d0 20 70 72 6f 63 65 73 73 20 73 68 75 74 64 6f 77   process shutdow
381e0 6e 2c 20 69 66 20 72 65 71 75 69 72 65 64 2e 0a  n, if required..
381f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74  **.** The xCreat
38200 65 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73  e() method is us
38210 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
38220 61 20 6e 65 77 20 63 61 63 68 65 20 69 6e 73 74  a new cache inst
38230 61 6e 63 65 2e 20 54 68 65 0a 2a 2a 20 66 69 72  ance. The.** fir
38240 73 74 20 70 61 72 61 6d 65 74 65 72 2c 20 73 7a  st parameter, sz
38250 50 61 67 65 2c 20 69 73 20 74 68 65 20 73 69 7a  Page, is the siz
38260 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
38270 65 20 70 61 67 65 73 20 74 68 61 74 20 6d 75 73  e pages that mus
38280 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f 63 61 74 65  t.** be allocate
38290 64 20 62 79 20 74 68 65 20 63 61 63 68 65 2e 20  d by the cache. 
382a0 73 7a 50 61 67 65 20 77 69 6c 6c 20 6e 6f 74 20  szPage will not 
382b0 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77  be a power of tw
382c0 6f 2e 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  o. The.** second
382d0 20 61 72 67 75 6d 65 6e 74 2c 20 62 50 75 72 67   argument, bPurg
382e0 65 61 62 6c 65 2c 20 69 73 20 74 72 75 65 20 69  eable, is true i
382f0 66 20 74 68 65 20 63 61 63 68 65 20 62 65 69 6e  f the cache bein
38300 67 20 63 72 65 61 74 65 64 20 77 69 6c 6c 0a 2a  g created will.*
38310 2a 20 62 65 20 75 73 65 64 20 74 6f 20 63 61 63  * be used to cac
38320 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
38330 73 20 72 65 61 64 20 66 72 6f 6d 20 61 20 66 69  s read from a fi
38340 6c 65 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 73  le stored on dis
38350 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73 65 20 69  k, or.** false i
38360 66 20 69 74 20 69 73 20 75 73 65 64 20 66 6f 72  f it is used for
38370 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   an in-memory da
38380 74 61 62 61 73 65 2e 20 54 68 65 20 63 61 63 68  tabase. The cach
38390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
383a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  .** does not hav
383b0 65 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67  e to do anything
383c0 20 73 70 65 63 69 61 6c 20 62 61 73 65 64 20 6f   special based o
383d0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 62  n the value of b
383e0 50 75 72 67 65 61 62 6c 65 2c 0a 2a 2a 20 69 74  Purgeable,.** it
383f0 20 69 73 20 70 75 72 65 6c 79 20 61 64 76 69 73   is purely advis
38400 6f 72 79 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ory. .**.** The 
38410 78 43 61 63 68 65 73 69 7a 65 28 29 20 6d 65 74  xCachesize() met
38420 68 6f 64 20 6d 61 79 20 62 65 20 63 61 6c 6c 65  hod may be calle
38430 64 20 61 74 20 61 6e 79 20 74 69 6d 65 20 62 79  d at any time by
38440 20 53 51 4c 69 74 65 20 74 6f 20 73 65 74 20 74   SQLite to set t
38450 68 65 0a 2a 2a 20 73 75 67 67 65 73 74 65 64 20  he.** suggested 
38460 6d 61 78 69 6d 75 6d 20 63 61 63 68 65 2d 73 69  maximum cache-si
38470 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66 20 70 61  ze (number of pa
38480 67 65 73 20 73 74 6f 72 65 64 20 62 79 29 20 74  ges stored by) t
38490 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 6e 73 74  he cache.** inst
384a0 61 6e 63 65 20 70 61 73 73 65 64 20 61 73 20 74  ance passed as t
384b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
384c0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 76  t. This is the v
384d0 61 6c 75 65 20 63 6f 6e 66 69 67 75 72 65 64 20  alue configured 
384e0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 53 51 4c  using.** the SQL
384f0 69 74 65 20 22 5b 50 52 41 47 4d 41 20 63 61 63  ite "[PRAGMA cac
38500 68 65 5f 73 69 7a 65 5d 22 20 63 6f 6d 6d 61 6e  he_size]" comman
38510 64 2e 20 41 73 20 77 69 74 68 20 74 68 65 20 62  d. As with the b
38520 50 75 72 67 65 61 62 6c 65 20 70 61 72 61 6d 65  Purgeable parame
38530 74 65 72 2c 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  ter,.** the impl
38540 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f  ementation is no
38550 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 64 6f  t required to do
38560 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61   anything specia
38570 6c 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 76  l with this.** v
38580 61 6c 75 65 2c 20 69 74 20 69 73 20 61 64 76 69  alue, it is advi
38590 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
385a0 20 54 68 65 20 78 50 61 67 65 63 6f 75 6e 74 28   The xPagecount(
385b0 29 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  ) method should 
385c0 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
385d0 72 20 6f 66 20 70 61 67 65 73 20 63 75 72 72 65  r of pages curre
385e0 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 65 64 20 69  ntly.** stored i
385f0 6e 20 74 68 65 20 63 61 63 68 65 20 73 75 70 70  n the cache supp
38600 6c 69 65 64 20 61 73 20 61 6e 20 61 72 67 75 6d  lied as an argum
38610 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ent..** .** The 
38620 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 20  xFetch() method 
38630 69 73 20 75 73 65 64 20 74 6f 20 66 65 74 63 68  is used to fetch
38640 20 61 20 70 61 67 65 20 61 6e 64 20 72 65 74 75   a page and retu
38650 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
38660 69 74 2e 20 0a 2a 2a 20 41 20 27 70 61 67 65 27  it. .** A 'page'
38670 2c 20 69 6e 20 74 68 69 73 20 63 6f 6e 74 65 78  , in this contex
38680 74 2c 20 69 73 20 61 20 62 75 66 66 65 72 20 6f  t, is a buffer o
38690 66 20 73 7a 50 61 67 65 20 62 79 74 65 73 20 61  f szPage bytes a
386a0 6c 69 67 6e 65 64 20 61 74 20 61 6e 0a 2a 2a 20  ligned at an.** 
386b0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
386c0 20 54 68 65 20 70 61 67 65 20 74 6f 20 62 65 20   The page to be 
386d0 66 65 74 63 68 65 64 20 69 73 20 64 65 74 65 72  fetched is deter
386e0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 6b 65 79  mined by the key
386f0 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d 69 6d 75 6d  . The.** mimimum
38700 20 6b 65 79 20 76 61 6c 75 65 20 69 73 20 31 2e   key value is 1.
38710 20 41 66 74 65 72 20 69 74 20 68 61 73 20 62 65   After it has be
38720 65 6e 20 72 65 74 72 69 65 76 65 64 20 75 73 69  en retrieved usi
38730 6e 67 20 78 46 65 74 63 68 2c 20 74 68 65 20 70  ng xFetch, the p
38740 61 67 65 20 0a 2a 2a 20 69 73 20 63 6f 6e 73 69  age .** is consi
38750 64 65 72 65 64 20 74 6f 20 62 65 20 70 69 6e 6e  dered to be pinn
38760 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
38770 20 72 65 71 75 65 73 74 65 64 20 70 61 67 65 20   requested page 
38780 69 73 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68  is already in th
38790 65 20 70 61 67 65 20 63 61 63 68 65 2c 20 74 68  e page cache, th
387a0 65 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  en a pointer to.
387b0 2a 2a 20 74 68 65 20 63 61 63 68 65 64 20 62 75  ** the cached bu
387c0 66 66 65 72 20 73 68 6f 75 6c 64 20 62 65 20 72  ffer should be r
387d0 65 74 75 72 6e 65 64 20 77 69 74 68 20 69 74 73  eturned with its
387e0 20 63 6f 6e 74 65 6e 74 73 20 69 6e 74 61 63 74   contents intact
387f0 2e 20