/ Hex Artifact Content
Login

Artifact 4a12a7193d4dcceef4f2c6a42a4b8c51f6ccd412:


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 32 20 32 30 30 39 2f 30  n,v 1.442 2009/0
05f0: 34 2f 31 39 20 31 32 3a 32 33 3a 35 38 20 64 72  4/19 12:23:58 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4190: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41a0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
41c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
41d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
41e0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
41f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4200: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4210: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
4220: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4230: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
4240: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
4260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4270: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
4280: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4290: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42a0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
42b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
42c0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
42d0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
42e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
42f0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4300: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
4320: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
4330: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
4340: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4350: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4360: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
4370: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4380: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4390: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
43a0: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
43b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
43c0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
43e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
43f0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
4400: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4410: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4420: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4430: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4440: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4450: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4460: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4470: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
4480: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
4490: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
44a0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
44b0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
44c0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
44d0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
44e0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
44f0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4500: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4510: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4520: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4530: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4540: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4550: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4560: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4570: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4580: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
45a0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
45b0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
45c0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
45d0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
45e0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
45f0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4600: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4610: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4620: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4630: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4640: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4650: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4660: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4670: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4680: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4690: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
46a0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
46b0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
46c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
46d0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
46e0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
46f0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4700: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4710: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4720: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4730: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4740: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4750: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4760: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4770: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4780: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4790: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
47a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
47b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47c0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
47d0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
47e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
47f0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4800: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4810: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4820: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4830: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4850: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4860: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4880: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4890: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
48a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48b0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
48c0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
48d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48e0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
48f0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4910: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4920: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4940: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4950: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4970: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4980: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4990: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
49a0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
49b0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
49c0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
49d0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
49e0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
49f0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4a00: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4a10: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4a20: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4a30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4a40: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4a50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4a60: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4a80: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4a90: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4aa0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4ab0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ad0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4ae0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4af0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4b10: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4b20: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4b30: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4b40: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4b50: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4b60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4b70: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4b80: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4b90: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4ba0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4bb0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4bc0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4bd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4be0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4bf0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4c00: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4c10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4c20: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4c30: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4c40: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4c50: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4c60: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4c70: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4c80: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4c90: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4ca0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4cb0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4cc0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4cd0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4ce0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4cf0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4d00: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4d10: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4d20: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4d30: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4d40: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4d50: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4d60: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4d70: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4d80: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4d90: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4da0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4db0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4dc0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4dd0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4df0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4e00: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4e10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4e20: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4e30: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4e40: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4e50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4e60: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4e70: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4e80: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4e90: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4ea0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4eb0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ec0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
4ed0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
4ee0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
4ef0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
4f00: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
4f10: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
4f20: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
4f30: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
4f40: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
4f50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
4f60: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
4f70: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
4f80: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
4f90: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
4fa0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
4fb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
4fd0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
4fe0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
4ff0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5000: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5010: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5020: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5030: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5050: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5060: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
5070: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
5080: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
5090: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
50a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
50b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
50c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
50d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
50f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5100: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5110: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5120: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5130: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5140: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5150: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5160: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
5170: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
5180: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
5190: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
51a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
51b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
51c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
51d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
51e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
51f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
5200: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
5210: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
5220: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
5230: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5240: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
5250: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
5260: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
5270: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
5280: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
5290: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
52a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
52b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
52c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
52d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
52e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
52f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
5300: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5310: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
5320: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
5330: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5340: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5350: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5360: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5370: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5380: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5390: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
53a0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
53c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
53d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
53e0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
53f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5400: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5410: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5420: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5430: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5440: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
5450: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5460: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5470: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
5480: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
5490: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
54a0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
54b0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
54c0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
54d0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
54e0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
54f0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
5500: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
5510: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
5520: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
5530: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
5540: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
5550: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
5560: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
5570: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
5580: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
5590: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
55a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
55b0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
55c0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
55d0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
55e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
55f0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
5600: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
5610: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
5620: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
5630: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
5640: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
5650: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
5660: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
5670: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
5680: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
5690: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
56a0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
56b0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
56c0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
56d0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
56e0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
56f0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
5700: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
5710: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
5720: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
5730: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
5740: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
5750: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
5760: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
5770: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
5780: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
5790: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
57a0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
57b0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
57c0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
57d0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
57e0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
57f0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
5800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5810: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5820: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
5830: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
5840: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
5850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
5860: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
5870: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
5880: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5890: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
58a0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
58b0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
58c0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
58d0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
58e0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
58f0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
5900: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
5910: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
5920: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
5930: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
5940: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
5950: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
5960: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
5970: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
5980: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
5990: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
59a0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
59b0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
59c0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
59d0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
59e0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
59f0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
5a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5a20: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
5a30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5a40: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
5a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a80: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
5a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5aa0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
5ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ac0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
5ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ae0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
5af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5b00: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
5b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b20: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5b40: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
5b50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5b60: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
5b70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
5b80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b90: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
5ba0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
5bb0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
5bc0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5be0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
5bf0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
5c00: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
5c10: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
5c20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
5c30: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
5c40: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
5c50: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
5c60: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
5c70: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
5c80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5c90: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
5ca0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
5cb0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
5cc0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5cd0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5ce0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5cf0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5d00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5d10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5d20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5d30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5d40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5d50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
5d70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5d80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5d90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5da0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5db0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
5dc0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
5dd0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5de0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
5df0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
5e00: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
5e10: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
5e20: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
5e30: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
5e40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
5e50: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
5e60: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
5e70: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
5e80: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
5e90: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
5ea0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
5eb0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
5ec0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
5ed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
5ef0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5f00: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
5f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
5f20: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
5f30: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
5f40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5f50: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
5f60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
5f70: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
5f80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
5f90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
5fa0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5fb0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
5fc0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
5fd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
5fe0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
5ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6000: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
6010: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
6020: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
6030: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6040: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6050: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6060: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6070: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6080: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6090: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
60a0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
60b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
60c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
60d0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
60e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
60f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
6100: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
6110: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
6120: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
6130: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
6140: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
6150: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6160: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
6170: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
6180: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
6190: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
61a0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
61b0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
61c0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
61d0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
61e0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
61f0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
6200: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
6210: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6220: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
6230: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
6240: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6250: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6270: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
6280: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6290: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
62a0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
62b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
62c0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
62d0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
62e0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
62f0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
6300: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
6310: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
6320: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
6330: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
6340: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
6350: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
6360: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6370: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
6380: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6390: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
63a0: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
63b0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
63c0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
63d0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
63e0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
63f0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
6400: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
6410: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
6420: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
6430: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
6440: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
6450: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
6460: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6470: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6480: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
6490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
64a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
64b0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
64c0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
64d0: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
64f0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
6500: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6510: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6520: 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30  le {H17110} <S20
6530: 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  130>.**.** The m
6540: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
6550: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
6560: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
6570: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
6580: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
6590: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
65a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
65b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
65c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
65d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
65e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
65f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
6600: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
6610: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
6620: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
6630: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
6640: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
6650: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
6660: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
6670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6680: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
6690: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
66a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
66b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
66c0: 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31  t {H11140} <S201
66d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00>.**.** An ins
66e0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
66f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
6700: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
6710: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
6720: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
6730: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
6740: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
6750: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
6760: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
6770: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
6780: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
6790: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
67a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
67b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
67c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
67d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
67e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
67f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
6800: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
6810: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
6820: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
6830: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
6840: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
6850: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
6860: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
6870: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
6880: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
6890: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
68a0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
68b0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
68c0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
68d0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
68e0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
68f0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
6900: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
6910: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6920: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6930: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6940: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6950: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6960: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6970: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6980: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6990: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
69a0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
69b0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
69c0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
69d0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
69e0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
69f0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6a00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6a10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6a20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6a30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6a40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6a50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6a60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6a70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6a80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6a90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
6aa0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
6ab0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
6ac0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
6ad0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
6ae0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
6af0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
6b00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
6b10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
6b20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
6b30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
6b40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
6b50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
6b60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
6b70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
6b80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6b90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6ba0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6bb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6bc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6bd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6be0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6bf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6c00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6c10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6c20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
6c30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
6c40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
6c50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
6c60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
6c70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
6c80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6c90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6ca0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6cb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6cc0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6cd0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6ce0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
6cf0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
6d00: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
6d10: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
6d20: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
6d30: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
6d40: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
6d50: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
6d60: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
6d70: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
6d80: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
6d90: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
6da0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
6db0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
6dc0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a  vious sentense,.
6dd0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
6de0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
6df0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6e00: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6e10: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6e20: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6e30: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6e40: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
6e50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
6e60: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
6e70: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6e80: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
6e90: 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73   must invite its
6ea0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
6eb0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
6ec0: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
6ed0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
6ee0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
6ef0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
6f00: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
6f10: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
6f20: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
6f30: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
6f40: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
6f50: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
6f60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
6f70: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
6f80: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
6f90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6fa0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
6fb0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
6fc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6fd0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
6fe0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
6ff0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7000: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7010: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7020: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7040: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
7050: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7060: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7070: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7080: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7090: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
70a0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
70b0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
70c0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
70d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
70e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
70f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7100: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7110: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7120: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7130: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7150: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7160: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7170: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7180: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7190: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
71a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
71b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
71c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
71d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
71e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
71f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7210: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7220: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7230: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7240: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7250: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7260: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7270: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7280: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7290: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
72a0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
72b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
72c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
72d0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
72e0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
72f0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
7300: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
7310: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
7320: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
7330: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
7340: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
7350: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
7360: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
7370: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
7380: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
7390: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
73a0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
73b0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
73c0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
73d0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
73e0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
73f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7400: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7410: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7420: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
7430: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
7440: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7450: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
7460: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
7470: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7480: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7490: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
74a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
74b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
74c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
74d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
74e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
74f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7500: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7510: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7520: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
7530: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7540: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
7550: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
7560: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
7570: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7580: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7590: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
75a0: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
75b0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
75c0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
75d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
75e0: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
75f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
7600: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
7610: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7620: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
7630: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
7640: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
7650: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
7660: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
7670: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
7680: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
7690: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
76a0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
76b0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
76c0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
76d0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
76e0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
76f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
7700: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7710: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
7720: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
7730: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
7740: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
7750: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it in..**.** The
7760: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7770: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7780: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7790: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
77a0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
77b0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
77c0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
77d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
77e0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
77f0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
7800: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
7810: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
7820: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
7830: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
7840: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
7850: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
7860: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
7870: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
7880: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
7890: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
78a0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
78b0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
78c0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
78d0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
78e0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
78f0: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7900: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
7910: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
7920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
7930: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
7940: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
7950: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
7960: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
7970: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
7980: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
7990: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
79a0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
79b0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
79c0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
79d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
79e0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
79f0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
7a00: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
7a10: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
7a20: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
7a30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
7a40: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
7a50: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
7a60: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
7a70: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
7a80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
7a90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
7aa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
7ab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
7ac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
7ad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
7ae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7af0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
7b00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
7b10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
7b20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
7b30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
7b40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
7b50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
7b60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
7b70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
7b80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
7b90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
7ba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
7bb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
7bc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
7bd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
7be0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
7bf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
7c00: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
7c10: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
7c20: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
7c30: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
7c40: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
7c50: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65  time..**.*/.type
7c60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7c70: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
7c80: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
7c90: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
7ca0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
7cb0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
7cc0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
7cd0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
7ce0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
7cf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
7d00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
7d10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
7d20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
7d30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
7d40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
7d50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
7d60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
7d70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
7d80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
7d90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
7da0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
7db0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
7dc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
7dd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
7de0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
7df0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
7e00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
7e10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
7e20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
7e30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
7e40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
7e60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
7e70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
7e80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
7e90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ea0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
7eb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
7ec0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
7ed0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
7ee0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
7ef0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
7f00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7f10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7f20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7f30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7f40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7f50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
7f60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
7f70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7f80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
7f90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7fb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7fc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7fd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
7fe0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
7ff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
8000: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
8010: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8020: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8030: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8040: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
8050: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8060: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8070: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8080: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8090: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
80a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
80b0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
80c0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
80d0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
80e0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
80f0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
8100: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
8110: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8120: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
8130: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
8140: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
8150: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
8160: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
8170: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
8180: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8190: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
81a0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48  ss VFS method {H
81b0: 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a  11190} <H11140>.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
81d0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
81e0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
81f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
8200: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
8210: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
8220: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
8230: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
8240: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
8250: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
8260: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
8270: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
8280: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
8290: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
82a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
82b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
82c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
82d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
82e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
82f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8300: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
8310: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
8320: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8330: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8340: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8350: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  le..** With SQLI
8360: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
8370: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8380: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
8390: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
83a0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64   readable..*/.#d
83b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
83c0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
83d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
83e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
83f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
8400: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
8410: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    2../*.** CAPI3
8420: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
8430: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
8440: 72 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30  ry {H10130} <S20
8450: 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  000><S30100>.**.
8460: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8470: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8480: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
8490: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
84a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
84b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
84c0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
84d0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
84e0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
84f0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
8500: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
8540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
8550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
8560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
8590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
85a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
85b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
85c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
85d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
85e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
85f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
8600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8610: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
8620: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
8630: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
8640: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
8650: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
8660: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
8670: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
8680: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
8690: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
86a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
86b0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
86c0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
86d0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
86e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
86f0: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
8700: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
8710: 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a  ialize().  Only.
8720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
8730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
8750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
8760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
8770: 65 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  er calls to sqli
8780: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
8790: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
87a0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ps..**.** Among 
87b0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
87c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
87d0: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
87e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
87f0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
8800: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
8810: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
8820: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
8830: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
8840: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8850: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
8860: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
8870: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
8880: 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61   If for some rea
8890: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
88a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
88b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
88c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
88d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
88e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
88f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
8900: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
8910: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
8920: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
8930: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
8940: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
8950: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
8960: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
8970: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
8980: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
8990: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
89a0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
89b0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
89c0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
89d0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
89e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
89f0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
8a00: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
8a10: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
8a20: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
8a30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8a40: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
8a50: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
8a60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
8a70: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
8a80: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8a90: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
8aa0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
8ab0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
8ac0: 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69  ady.  However, i
8ad0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
8ae0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
8af0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
8b00: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
8b10: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
8b20: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
8b30: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
8b40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
8b50: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
8b60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8b70: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
8b80: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8b90: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
8ba0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
8bb0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
8bc0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
8bd0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
8be0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
8bf0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
8c00: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
8c10: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
8c20: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
8c30: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
8c40: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
8c50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
8c60: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
8c70: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
8c80: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
8c90: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
8ca0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
8cb0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
8cc0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
8cd0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
8ce0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
8cf0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
8d00: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
8d10: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
8d20: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
8d30: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
8d40: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
8d50: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
8d60: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
8d70: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
8d80: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
8d90: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
8da0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
8db0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
8dc0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
8dd0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
8de0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
8df0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
8e00: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
8e10: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
8e20: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
8e30: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
8e40: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
8e50: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
8e60: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
8e70: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
8e80: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
8e90: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
8ea0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
8eb0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
8ec0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
8ed0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
8ee0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
8ef0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8f00: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
8f10: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
8f20: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
8f30: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
8f40: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
8f50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8f60: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
8f70: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
8f80: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
8f90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8fa0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
8fb0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
8fc0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
8fd0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
8fe0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8ff0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
9000: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
9010: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
9020: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9030: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
9040: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9050: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
9060: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
9070: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
9080: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
9090: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
90a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78  ompiled for unix
90b0: 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73  , windows, or os
90c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c  /2..** When buil
90d0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
90e0: 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65  forms (using the
90f0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
9100: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
9110: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
9120: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
9130: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
9140: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
9150: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
9160: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9170: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9180: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
9190: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
91a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
91b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
91c0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
91d0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
91e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
91f0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
9200: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
9210: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
9220: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
9230: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9240: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
9250: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
9260: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
9270: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
9280: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9290: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
92a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
92b0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
92c0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31  te Library {H141
92d0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30  00} <S20000><S30
92e0: 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
92f0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
9300: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9310: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
9320: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
9330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
9340: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
9350: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
9360: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
9370: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
9380: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
9390: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
93a0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
93b0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
93c0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
93d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
93e0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
93f0: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
9400: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
9410: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
9420: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
9430: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
9440: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
9450: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9460: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9470: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
9480: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
9490: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
94a0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
94b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
94c0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
94d0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
94e0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
94f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9500: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
9510: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
9520: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
9530: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
9540: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
9550: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
9560: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
9570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
9580: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
9590: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
95a0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74  tdown()]..** Not
95b0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
95c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
95d0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
95e0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
95f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9600: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
9610: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
9620: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
9630: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
9640: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
9650: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
9660: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
9670: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
9680: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
9690: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
96a0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
96b0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
96c0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
96d0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
96e0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
96f0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
9700: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
9710: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
9720: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
9730: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
9740: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
9750: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
9760: 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66  *.** When a conf
9770: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
9780: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
9790: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
97a0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
97b0: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
97c0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
97d0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
97e0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
97f0: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
9800: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
9810: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
9820: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  code]..**.** Req
9830: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
9840: 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20  14103] [H14106] 
9850: 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33  [H14120] [H14123
9860: 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31  ] [H14126] [H141
9870: 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31  29] [H14132] [H1
9880: 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38  4135].** [H14138
9890: 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31  ] [H14141] [H141
98a0: 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31  44] [H14147] [H1
98b0: 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b  4150] [H14153] [
98c0: 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d  H14156] [H14159]
98d0: 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31  .** [H14162] [H1
98e0: 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a  4165] [H14168].*
98f0: 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
9900: 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
9910: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
9920: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
9930: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
9940: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9950: 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53  ons  {H14200} <S
9960: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
9970: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
9980: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
9990: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
99a0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
99b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
99c0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
99d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99e0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
99f0: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
9a00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
9a10: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
9a20: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
9a30: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
9a40: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
9a50: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
9a60: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
9a70: 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68  t argument).  Th
9a80: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  e.** sqlite3_db_
9a90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
9aa0: 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  ce can only be u
9ab0: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
9ac0: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
9ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ae0: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
9af0: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
9b00: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
9b10: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
9b20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
9b30: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
9b40: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9b50: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
9b60: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
9b70: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
9b80: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
9b90: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
9ba0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
9bb0: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
9bc0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
9bd0: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
9be0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
9bf0: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
9c00: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
9c10: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
9c20: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
9c30: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
9c40: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
9c50: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9c60: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
9c70: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
9c80: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
9c90: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
9ca0: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
9cb0: 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31  .** [H14203] [H1
9cc0: 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b  4206] [H14209] [
9cd0: 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d  H14212] [H14215]
9ce0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
9cf0: 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
9d00: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
9d10: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
9d20: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
9d30: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
9d40: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
9d50: 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31  s {H10155} <S201
9d60: 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  20>.** EXPERIMEN
9d70: 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  TAL.**.** An ins
9d80: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
9d90: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
9da0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
9db0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
9dc0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
9dd0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
9de0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
9df0: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
9e00: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
9e10: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
9e20: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
9e30: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e40: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9e50: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
9e60: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
9e70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
9e80: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
9e90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
9ea0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
9eb0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20  IG_MALLOC].  By 
9ec0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
9ed0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
9ee0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
9ef0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
9f00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69  3_config()] duri
9f10: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
9f20: 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  , an.** applicat
9f30: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
9f40: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  an alternative m
9f50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
9f60: 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f   subsystem.** fo
9f70: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
9f80: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
9f90: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
9fa0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
9fb0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
9fc0: 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69  s with a built-i
9fd0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
9fe0: 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65  or that is.** pe
9ff0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
a000: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
a010: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
a020: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
a030: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
a040: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
a050: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
a060: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
a070: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
a080: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
a090: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
a0a0: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
a0b0: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
a0c0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
a0d0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
a0e0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
a0f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
a100: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
a110: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
a120: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
a130: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
a140: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
a150: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
a160: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
a170: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
a180: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
a190: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
a1a0: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65  e xMalloc, xFree
a1b0: 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d  , and xRealloc m
a1c0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
a1d0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
a1e0: 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61  loc(), free(), a
a1f0: 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e  nd realloc() fun
a200: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
a210: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
a220: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
a230: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
a240: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a250: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
a260: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
a270: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
a280: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
a290: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
a2a0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
a2b0: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
a2c0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
a2d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
a2e0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
a2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
a300: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
a310: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
a320: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
a330: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
a340: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
a350: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
a360: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
a370: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
a380: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
a390: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
a3a0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
a3b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
a3c0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
a3d0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
a3e0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
a3f0: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
a400: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
a410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
a420: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
a430: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
a440: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
a450: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
a460: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
a470: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
a480: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
a490: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
a4a0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
a4b0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
a4c0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
a4d0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
a4e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
a4f0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
a500: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
a510: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
a520: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
a530: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
a540: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
a550: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
a560: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
a570: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
a580: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a590: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5a0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
a5b0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
a5c0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a5d0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
a5e0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
a5f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
a600: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
a610: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
a620: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
a630: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
a640: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
a650: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
a660: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
a670: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
a680: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
a690: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
a6a0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
a6b0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
a6c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
a6d0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
a6e0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
a6f0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
a700: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
a710: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
a720: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
a730: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
a740: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
a750: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
a760: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a770: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
a780: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
a790: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
a7a0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
a7b0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
a7c0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
a7e0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
a7f0: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
a800: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
a810: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
a820: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
a830: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30  s {H10160} <S200
a840: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a850: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
a860: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
a870: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
a880: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
a890: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
a8a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
a8b0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
a8c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
a8d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
a8e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
a8f0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
a900: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
a910: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
a920: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
a930: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
a940: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
a950: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
a960: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
a970: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
a980: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
a990: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
a9a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
a9b0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
a9c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
a9d0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
a9e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a9f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
aa00: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
aa10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
aa20: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
aa30: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
aa40: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
aa50: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
aa60: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
aa70: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
aa80: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
aa90: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
aaa0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
aab0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
aac0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
aad0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
aae0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
aaf0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
ab00: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
ab10: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
ab20: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
ab30: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e  gle thread.</dd>
ab40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ab50: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
ab60: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ab70: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ab80: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ab90: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
aba0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
abb0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
abc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
abd0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
abe0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
abf0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
ac00: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
ac10: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
ac20: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
ac30: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
ac40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
ac50: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
ac60: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
ac70: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
ac80: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
ac90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
aca0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
acb0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
acc0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
acd0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
ace0: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
acf0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
ad00: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ad10: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
ad20: 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20  same time.  See 
ad30: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
ad40: 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74  ode].** document
ad50: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
ad60: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
ad70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ad80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ad90: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
ada0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
adb0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
adc0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
add0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ade0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
adf0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ae00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ae10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
ae20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ae30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ae40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ae50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
ae60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
ae70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
ae80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ae90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
aea0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
aeb0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
aec0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
aed0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
aee0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
aef0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
af00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
af10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
af20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
af30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
af40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
af50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
af60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
af70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
af80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
af90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
afa0: 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68   time..** See th
afb0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
afc0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
afd0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
afe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
aff0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b000: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
b010: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b020: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b030: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b040: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b050: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b060: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b070: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b080: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b090: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
b0a0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
b0b0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
b0c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b0d0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
b0e0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
b0f0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b100: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b110: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
b120: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
b130: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b140: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
b150: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b160: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
b170: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
b180: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
b190: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
b1a0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
b1b0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
b1c0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
b1d0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b1e0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
b1f0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
b200: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
b210: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
b220: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
b230: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
b240: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
b250: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
b260: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
b270: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
b280: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
b290: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
b2a0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
b2b0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
b2c0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
b2d0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
b2e0: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
b2f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b300: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
b310: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
b320: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
b330: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
b340: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
b350: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
b360: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
b370: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
b380: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
b390: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
b3a0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
b3b0: 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65  cs. When disable
b3c0: 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
b3d0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
b3e0: 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f  es become .** no
b3f0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
b400: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
b410: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
b420: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
b430: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b440: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
b450: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b460: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
b470: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
b480: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
b490: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a  s()].**   </ul>.
b4a0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
b4b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b4c0: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
b4d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b4e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
b4f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
b500: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
b510: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
b520: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
b530: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
b540: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
b550: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
b560: 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  y, the.** size o
b570: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62  f each scratch b
b580: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
b590: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75  the number of bu
b5a0: 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20  ffers (N).  The 
b5b0: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
b5c0: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
b5d0: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20  e of 16. The sz 
b5e0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b5f0: 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a   be a few bytes.
b600: 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  ** larger than t
b610: 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63  he actual scratc
b620: 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  h space required
b630: 20 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76   due internal ov
b640: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
b650: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
b660: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
b670: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
b680: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
b690: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
b6a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
b6b0: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
b6c0: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
b6d0: 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20  fer at once per 
b6e0: 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20  thread, so.** N 
b6f0: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
b700: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
b710: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b720: 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a  threads.  The sz
b730: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68  .** parameter sh
b740: 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20  ould be 6 times 
b750: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b760: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
b770: 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53   page size..** S
b780: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61  cratch buffers a
b790: 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20  re used as part 
b7a0: 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c  of the btree bal
b7b0: 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  ance operation. 
b7c0: 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65   If.** The btree
b7d0: 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20   balancer needs 
b7e0: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  additional memor
b7f0: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
b800: 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20   provided by.** 
b810: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
b820: 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68  or if no scratch
b830: 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73   buffer space is
b840: 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
b850: 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20   SQLite.** goes 
b860: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
b870: 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20  oc()] to obtain 
b880: 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65  the memory it ne
b890: 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  eds.</dd>.**.** 
b8a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
b8b0: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
b8c0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b8d0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
b8e0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
b8f0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
b900: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
b910: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
b920: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
b930: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
b940: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
b950: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
b960: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
b970: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
b980: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
b990: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
b9a0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
b9b0: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
b9c0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
b9d0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
b9e0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
b9f0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ba00: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ba10: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
ba20: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  he.** memory, th
ba30: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
ba40: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
ba50: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
ba60: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
ba70: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
ba80: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72   must be a power
ba90: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
baa0: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20  512 and 32768.  
bab0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
bac0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
bad0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
bae0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
baf0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
bb00: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
bb10: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
bb20: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
bb30: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bb40: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
bb50: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
bb60: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
bb70: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
bb80: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
bb90: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
bba0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
bbb0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
bbc0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bbd0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
bbe0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
bbf0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
bc00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
bc10: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
bc20: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
bc30: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
bc40: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
bc50: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
bc60: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
bc70: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
bc80: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
bc90: 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a  rmation. </dd>.*
bca0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
bcb0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
bcc0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bcd0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
bce0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
bcf0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
bd00: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
bd10: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
bd20: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
bd30: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
bd40: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
bd50: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
bd60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
bd70: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
bd80: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
bd90: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
bda0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
bdb0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
bdc0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75  e memory, the nu
bdd0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
bde0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
bdf0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
be00: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
be10: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74  n size.  If.** t
be20: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
be30: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
be40: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
be50: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
be60: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
be70: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
be80: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
be90: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
bea0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
beb0: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
bec0: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
bed0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
bee0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
bef0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
bf00: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
bf10: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
bf20: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
bf30: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
bf40: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
bf50: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
bf60: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
bf70: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
bf80: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
bf90: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
bfa0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
bfb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfc0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
bfd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bfe0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
bff0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c000: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c010: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c020: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c030: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c040: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c050: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
c060: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
c070: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
c080: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
c090: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
c0a0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c0b0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
c0c0: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
c0d0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
c0e0: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
c0f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c100: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
c110: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c120: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c130: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c140: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c150: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c160: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c170: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
c180: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
c190: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
c1a0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
c1b0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c1c0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c1d0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
c1e0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
c1f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
c200: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
c210: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
c220: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
c230: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
c240: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
c250: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
c260: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
c270: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
c280: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
c290: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c2a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c2b0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c2c0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DE</dt>.** <dd>T
c2d0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c2e0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
c2f0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
c300: 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
c310: 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f  ory allcation lo
c320: 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61  okaside optimiza
c330: 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74  tion.  The first
c340: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
c350: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
c360: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
c370: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
c380: 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
c390: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
c3a0: 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
c3b0: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
c3c0: 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
c3d0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c3e0: 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a  FIG_PCACHE</dt>.
c3f0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c400: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c410: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c420: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c430: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
c440: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
c450: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
c460: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
c470: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
c480: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
c490: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
c4a0: 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d  ation.  SQLite m
c4b0: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
c4c0: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
c4d0: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
c4e0: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
c4f0: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
c500: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c510: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
c520: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  HE</dt>.** <dd>T
c530: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c540: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c550: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c560: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
c570: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
c580: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
c590: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
c5a0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
c5b0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
c5c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
c5d0: 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  that object.</dd
c5e0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c610: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
c620: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c630: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
c640: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
c650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c660: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
c670: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
c680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c690: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
c6a0: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
c6b0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c6c0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
c6d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c6e0: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
c6f0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c700: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
c720: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
c730: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
c740: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
c750: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c760: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
c770: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
c780: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
c790: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c7a0: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
c7b0: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
c7c0: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
c7d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c7e0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c7f0: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
c800: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
c810: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c820: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
c830: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c840: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c850: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c860: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
c870: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
c880: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c890: 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
c8a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
c8b0: 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
c8c0: 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
c8d0: 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
c8e0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
c8f0: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
c900: 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
c910: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
c920: 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
c930: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
c940: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c960: 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
c970: 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
c980: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
c990: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
c9a0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
c9b0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
c9c0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
c9d0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
c9e0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
c9f0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
ca00: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ca10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ca20: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ca30: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
ca40: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ca50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
ca60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ca70: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
ca80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca90: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
caa0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
cab0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
cac0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
cad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cae0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
caf0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
cb00: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
cb10: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
cb20: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
cb30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cb40: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
cb50: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
cb60: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
cb70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cb80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
cb90: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
cba0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
cbb0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
cbc0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
cbd0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
cbe0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
cbf0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
cc00: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
cc10: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
cc20: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
cc30: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
cc40: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
cc50: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
cc60: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
cc70: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
cc80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
cc90: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
cca0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
ccb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
ccc0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
ccd0: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
cce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
ccf0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cd00: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
cd10: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
cd20: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
cd30: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
cd40: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
cd50: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
cd60: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
cd70: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
cd80: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
cd90: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
cda0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
cdb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cdc0: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
cdd0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
cde0: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
cdf0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
ce00: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
ce10: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
ce20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ce30: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
ce40: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
ce50: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ce60: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
ce70: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
ce80: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
ce90: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
cea0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
ceb0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
cec0: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
cee0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
cef0: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
cf00: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
cf10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
cf20: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
cf30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
cf40: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
cf50: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
cf60: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
cf70: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
cf80: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
cf90: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
cfa0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
cfb0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
cfc0: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
cfd0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
cfe0: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
cff0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d000: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
d010: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
d020: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
d030: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
d040: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d  nts:.** [H12201]
d050: 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74   [H12202].*/.int
d060: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
d070: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
d080: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
d090: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
d0a0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
d0b0: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
d0c0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
d0d0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
d0e0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
d0f0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
d100: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
d110: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
d120: 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
d130: 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20  id"]. The rowid 
d140: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
d150: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
d160: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
d170: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
d180: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
d190: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
d1a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
d1b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
d1c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
d1d0: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68  olumns. If.** th
d1e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
d1f0: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
d200: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
d210: 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
d220: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
d230: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
d240: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
d250: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d260: 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
d270: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
d280: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
d290: 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
d2a0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
d2b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
d2c0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
d2d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d2e0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
d2f0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
d300: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
d310: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
d320: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d330: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
d340: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
d350: 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
d360: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
d370: 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
d380: 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
d390: 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
d3a0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
d3b0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
d3c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
d3d0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
d3e0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
d3f0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
d400: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d410: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
d420: 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
d430: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
d440: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
d450: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
d460: 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54  **.** An [INSERT
d470: 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
d480: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
d490: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
d4a0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
d4b0: 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
d4c0: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
d4d0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d4e0: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
d4f0: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
d500: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
d510: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
d520: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
d530: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
d540: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
d550: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
d560: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
d570: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
d580: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
d590: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
d5a0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
d5b0: 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
d5c0: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
d5d0: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
d5e0: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
d5f0: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
d600: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
d610: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
d620: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
d630: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
d640: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
d650: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
d660: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
d670: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
d680: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
d690: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
d6a0: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
d6b0: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
d6c0: 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
d6d0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
d6e0: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
d6f0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
d700: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
d710: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
d720: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
d730: 20 5b 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32   [H12221] [H1222
d740: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
d750: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
d760: 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
d770: 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
d780: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
d790: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
d7a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
d7b0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d7c0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
d7d0: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
d7e0: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
d7f0: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
d800: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
d810: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
d820: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
d830: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
d840: 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
d850: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
d860: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
d870: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
d880: 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
d890: 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
d8a0: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
d8b0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
d8c0: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
d8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d8e0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
d8f0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
d900: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
d910: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
d920: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
d930: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
d940: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
d950: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
d960: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
d970: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
d980: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
d990: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
d9a0: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
d9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d9c0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
d9d0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
d9e0: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
d9f0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
da00: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
da10: 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
da20: 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
da30: 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
da40: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
da50: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
da60: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
da70: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
da80: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
da90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
daa0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
dab0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
dac0: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
dad0: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
dae0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
daf0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
db00: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
db10: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
db20: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
db30: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
db40: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
db50: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
db60: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
db70: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
db80: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
db90: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
dba0: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
dbb0: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
dbc0: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
dbd0: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
dbe0: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
dbf0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
dc00: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
dc10: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
dc20: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
dc30: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
dc40: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
dc50: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
dc60: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
dc70: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
dc80: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
dc90: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
dca0: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
dcb0: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
dcc0: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
dcd0: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
dce0: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
dcf0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
dd00: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
dd10: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
dd20: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
dd30: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
dd40: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
dd50: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
dd60: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
dd70: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
dd80: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
dd90: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
dda0: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
ddb0: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
ddc0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
ddd0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
dde0: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
ddf0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
de00: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
de10: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
de20: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
de30: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
de40: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
de50: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
de60: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
de70: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
de80: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
de90: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
dea0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
deb0: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
dec0: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
ded0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
dee0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
def0: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
df00: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
df10: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
df20: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
df30: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
df40: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
df50: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
df60: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
df70: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
df80: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
df90: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
dfa0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
dfb0: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
dfc0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
dfd0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
dfe0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
dff0: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
e000: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
e010: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
e020: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
e030: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
e040: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
e050: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
e060: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
e070: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
e080: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
e090: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
e0a0: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
e0b0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
e0c0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
e0d0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
e0e0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
e0f0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
e100: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
e110: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
e120: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
e130: 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d 75 63   Doing so is muc
e140: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
e150: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
e160: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
e170: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
e180: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 20  from the table. 
e190: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
e1a0: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e1b0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
e1c0: 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
e1d0: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
e1e0: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
e1f0: 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
e200: 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
e210: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
e220: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
e230: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
e240: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
e250: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
e260: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
e270: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
e280: 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
e290: 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
e2a0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
e2b0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
e2c0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
e2d0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
e2e0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
e2f0: 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 72 65   instead.  Or re
e300: 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68  compile using th
e310: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  e.** [SQLITE_OMI
e320: 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d  T_TRUNCATE_OPTIM
e330: 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65  IZATION] compile
e340: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20  -time option to 
e350: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f  disable the.** o
e360: 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61  ptimization on a
e370: 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  ll queries..**.*
e380: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
e390: 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32  ** [H12241] [H12
e3a0: 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  243].**.** If a 
e3b0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
e3c0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
e3d0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
e3e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
e3f0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
e400: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
e410: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
e420: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
e430: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
e440: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
e450: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
e460: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
e470: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
e480: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
e490: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
e4a0: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
e4b0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
e4c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e4d0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e4e0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
e4f0: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
e500: 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45  .** UPDATE or DE
e510: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
e520: 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
e530: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e540: 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54  was opened..** T
e550: 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
e560: 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
e570: 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63  om all trigger c
e580: 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65  ontexts.  Howeve
e590: 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
e5a0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
e5b0: 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
e5c0: 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41   implement REPLA
e5d0: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  CE constraints,.
e5e0: 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
e5f0: 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
e600: 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62  ing, or DROP tab
e610: 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a  le processing..*
e620: 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72  * The changes ar
e630: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
e640: 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
e650: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
e660: 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  em is.** complet
e670: 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
e680: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
e690: 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
e6a0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
e6b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
e6c0: 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
e6d0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
e6e0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
e6f0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
e700: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
e710: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
e720: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
e730: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
e740: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
e750: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
e760: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
e770: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
e780: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
e790: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
e7a0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
e7b0: 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
e7c0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
e7d0: 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
e7e0: 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
e7f0: 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
e800: 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
e810: 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
e820: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
e830: 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
e840: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
e850: 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
e860: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
e870: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
e880: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
e890: 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
e8a0: 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
e8b0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
e8c0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
e8d0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
e8e0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
e8f0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
e900: 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 20 72   instead.   Or r
e910: 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74  ecompile using t
e920: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  he.** [SQLITE_OM
e930: 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49  IT_TRUNCATE_OPTI
e940: 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c  MIZATION] compil
e950: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f  e-time option to
e960: 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
e970: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20  optimization on 
e980: 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  all queries..**.
e990: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
e9a0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
e9b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
e9c0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
e9d0: 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20 5b  s:.** [H12261] [
e9e0: 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12263].**.** If
e9f0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
ea00: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
ea10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
ea20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ea30: 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
ea40: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
ea50: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
ea60: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
ea70: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
ea80: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
ea90: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
eaa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
eab0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
eac0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
ead0: 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
eae0: 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
eaf0: 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20   Query {H12270} 
eb00: 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30500>.**.** T
eb10: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
eb20: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
eb30: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
eb40: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
eb50: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
eb60: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
eb70: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
eb80: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
eb90: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
eba0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
ebb0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
ebc0: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
ebd0: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
ebe0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
ebf0: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
ec00: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
ec10: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
ec20: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
ec30: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
ec40: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
ec50: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
ec60: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
ec70: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
ec80: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
ec90: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
eca0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
ecb0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
ecc0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
ecd0: 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
ece0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
ecf0: 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
ed00: 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
ed10: 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
ed20: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
ed30: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
ed40: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
ed50: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
ed60: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
ed70: 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
ed80: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
ed90: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
eda0: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
edb0: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
edc0: 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
edd0: 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
ede0: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
edf0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53  tion..**.** An S
ee00: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
ee10: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
ee20: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
ee30: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
ee40: 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72  .** If the inter
ee50: 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
ee60: 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
ee70: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
ee80: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
ee90: 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
eea0: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
eeb0: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
eec0: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
eed0: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
eee0: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
eef0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
ef00: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
ef10: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
ef20: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
ef30: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
ef40: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
ef50: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ef60: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
ef70: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
ef80: 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b 48 31  .** [H12271] [H1
ef90: 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  2272].**.** If t
efa0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
efb0: 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
efc0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
efd0: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
efe0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
eff0: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
f000: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
f010: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
f020: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
f030: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f040: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
f050: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
f060: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30  Is Complete {H10
f070: 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a  510} <S70200>.**
f080: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
f090: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
f0a0: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
f0b0: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
f0c0: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
f0d0: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
f0e0: 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
f0f0: 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20   complete a SQL 
f100: 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
f110: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
f120: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
f130: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
f140: 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
f150: 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
f160: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
f170: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
f180: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
f190: 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
f1a0: 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
f1b0: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20  L statement.  A 
f1c0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
f1d0: 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
f1e0: 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
f1f0: 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
f200: 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
f210: 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66  ot a fragment of
f220: 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49   a.** CREATE TRI
f230: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
f240: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74   Semicolons that
f250: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
f260: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
f270: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
f280: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
f290: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
f2a0: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
f2b0: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
f2c0: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
f2d0: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
f2e0: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
f2f0: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
f300: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
f310: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
f320: 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
f330: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
f340: 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
f350: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
f360: 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
f370: 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
f380: 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
f390: 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  L..**.** Require
f3a0: 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 5d 20  ments: [H10511] 
f3b0: 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54  [H10512].**.** T
f3c0: 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
f3d0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
f3e0: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
f3f0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
f400: 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
f410: 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
f420: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f430: 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
f440: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
f450: 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
f460: 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
f470: 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
f480: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
f490: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
f4a0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
f4b0: 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
f4c0: 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
f4d0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
f4e0: 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
f4f0: 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
f500: 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32  BUSY Errors {H12
f510: 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a  310} <S40400>.**
f520: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
f530: 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
f540: 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
f550: 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
f560: 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
f570: 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
f580: 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
f590: 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
f5a0: 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
f5b0: 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
f5c0: 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  cked..**.** If t
f5d0: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
f5e0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
f5f0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
f600: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
f610: 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
f620: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
f630: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
f640: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66  ing the lock. If
f650: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
f660: 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
f670: 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
f680: 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
f690: 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
f6a0: 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
f6b0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f6c0: 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72  t to the handler
f6d0: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
f6e0: 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
f6f0: 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
f700: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
f710: 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
f720: 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73  andler().  The s
f730: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f740: 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
f750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
f760: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
f770: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
f780: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
f790: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
f7a0: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
f7b0: 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  t.  If the.** bu
f7c0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
f7d0: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
f7e0: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
f7f0: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
f800: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
f810: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
f820: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
f830: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
f840: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
f850: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
f860: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
f870: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
f880: 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
f890: 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
f8a0: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
f8b0: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
f8c0: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
f8d0: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
f8e0: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
f8f0: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
f900: 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
f910: 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
f920: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
f930: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66  k contention. If
f940: 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
f950: 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
f960: 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
f970: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
f980: 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
f990: 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
f9a0: 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
f9b0: 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
f9c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
f9d0: 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
f9e0: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
f9f0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
fa00: 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
fa10: 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
fa20: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
fa30: 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
fa40: 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
fa50: 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
fa60: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
fa70: 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
fa80: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
fa90: 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
faa0: 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
fab0: 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
fac0: 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
fad0: 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
fae0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
faf0: 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
fb00: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
fb10: 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
fb20: 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
fb30: 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
fb40: 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
fb50: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
fb60: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
fb70: 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
fb80: 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
fb90: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
fba0: 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
fbb0: 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
fbc0: 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
fbd0: 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
fbe0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
fbf0: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
fc00: 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
fc10: 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
fc20: 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
fc30: 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
fc40: 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
fc50: 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
fc60: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
fc70: 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
fc80: 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
fc90: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
fca0: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
fcb0: 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
fcc0: 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
fcd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
fce0: 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
fcf0: 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
fd00: 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
fd10: 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
fd20: 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
fd30: 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
fd40: 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
fd50: 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
fd60: 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
fd70: 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
fd80: 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
fd90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
fda0: 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
fdb0: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
fdc0: 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
fdd0: 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
fde0: 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
fdf0: 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
fe00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
fe10: 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
fe20: 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
fe30: 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
fe40: 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
fe50: 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
fe60: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
fe70: 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
fe80: 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
fe90: 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
fea0: 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
feb0: 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
fec0: 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
fed0: 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
fee0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
fef0: 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
ff00: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
ff10: 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
ff20: 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
ff30: 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
ff40: 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
ff50: 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
ff60: 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
ff70: 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
ff80: 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
ff90: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
ffa0: 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
ffb0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
ffc0: 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
ffd0: 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
ffe0: 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
fff0: 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
10000 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ant..**.** There
10010 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
10020 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
10030 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
10040 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
10050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
10060 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
10070 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
10080 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
10090 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20  ly set handler. 
100a0 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
100b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
100c0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
100d0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
100e0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
100f0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
10100 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
10110 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
10120 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
10130 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
10140 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10150 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
10160 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10170 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
10180 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
10190 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
101a0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71  vior..** .** Req
101b0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
101c0 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32 5d 20  12311] [H12312] 
101d0 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33 31 36  [H12314] [H12316
101e0 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a  ] [H12318].**.**
101f0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
10200 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
10210 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
10220 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
10230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10240 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
10250 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10260 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10270 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
10280 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
10290 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
102a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
102b0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
102c0 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20 3c  meout {H12340} <
102d0 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
102e0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
102f0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
10300 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
10310 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
10320 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
10330 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
10340 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
10350 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
10360 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
10370 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
10380 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
10390 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
103a0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
103b0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
103c0 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33 34  umulated. {H1234
103d0 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69  3} After "ms" mi
103e0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
103f0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
10400 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
10410 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
10420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
10430 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
10440 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10450 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10460 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ED]..**.** Calli
10470 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
10480 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
10490 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
104a0 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
104b0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
104c0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
104d0 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
104e0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
104f0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
10500 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
10510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10520 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
10530 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
10540 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
10550 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
10560 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
10570 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10580 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
10590 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
105a0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
105b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
105c0 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   cleared..**.** 
105d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
105e0 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32 33 34   [H12341] [H1234
105f0 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f 0a 69  3] [H12344].*/.i
10600 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
10610 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
10620 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
10630 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
10640 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
10650 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
10660 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53  ries {H12370} <S
10670 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66  10000>.**.** Def
10680 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
10690 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
106a0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
106b0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
106c0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
106d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
106e0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
106f0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
10700 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
10710 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
10720 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
10730 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
10740 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
10750 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
10760 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
10770 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
10780 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
10790 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
107a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
107b0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
107c0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
107d0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
107e0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
107f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
10800 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
10810 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
10820 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
10830 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
10840 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
10850 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
10860 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
10870 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
10880 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
10890 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
108a0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
108b0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
108c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
108d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
108e0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
108f0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
10900 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
10910 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
10920 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
10930 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
10940 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
10950 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
10960 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
10970 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
10980 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
10990 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
109a0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
109b0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
109c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
109d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
109e0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
109f0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
10a00 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
10a10 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
10a20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
10a30 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
10a40 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
10a50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10a60 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
10a70 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
10a80 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
10a90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
10aa0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
10ab0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
10ac0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10ad0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
10ae0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
10af0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
10b00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
10b10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
10b20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
10b30 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
10b40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10b50 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
10b60 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
10b70 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
10b80 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
10b90 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
10ba0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
10bb0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
10bc0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
10bd0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
10be0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
10bf0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
10c00 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
10c10 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
10c20 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
10c30 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
10c40 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
10c50 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
10c60 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
10c70 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
10c80 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
10c90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
10ca0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10cb0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
10cc0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
10cd0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
10ce0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
10cf0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
10d00 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
10d10 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10d20 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
10d30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10d40 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
10d50 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
10d60 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
10d70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10d80 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
10d90 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
10da0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
10db0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
10dc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
10dd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10de0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
10df0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
10e00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
10e10 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
10e20 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
10e30 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
10e40 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
10e50 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
10e60 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
10e70 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
10e80 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
10e90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
10ea0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
10eb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
10ec0 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
10ed0 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
10ee0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
10ef0 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
10f00 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
10f10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
10f20 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
10f30 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
10f40 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
10f50 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
10f60 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
10f70 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
10f80 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
10f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
10fa0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
10fb0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
10fc0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
10fd0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
10fe0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
10ff0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
11000 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
11010 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
11020 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
11030 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
11040 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
11050 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
11060 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
11070 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11080 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11090 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
110a0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
110b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
110c0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
110d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
110e0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
110f0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
11100 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
11110 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
11120 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
11130 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
11140 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
11150 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
11160 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
11170 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
11180 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
11190 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
111a0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
111b0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
111c0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
111d0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
111e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
111f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
11200 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
11210 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
11220 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
11230 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b  s:.** [H12371] [
11240 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37 34 5d  H12373] [H12374]
11250 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 33 37   [H12376] [H1237
11260 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 69  9] [H12382].*/.i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
11280 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
11290 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
112a0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
112b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
112c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
112d0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
112e0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
112f0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
11300 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
11310 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
11320 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
11330 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
11340 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
11350 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
11360 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
11370 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
11380 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
11390 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
113a0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
113b0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
113c0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
113d0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
113e0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
113f0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
11400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11410 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
11420 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
11430 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37  ons {H17400} <S7
11440 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a  0000><S20000>.**
11450 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11460 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
11470 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
11480 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
11490 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
114a0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
114b0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
114c0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
114d0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
114e0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
114f0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
11500 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
11510 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
11520 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
11530 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
11540 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
11550 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
11560 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
11570 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
11580 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
11590 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
115a0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
115b0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
115c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
115d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
115e0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
115f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
11600 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
11610 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
11620 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11630 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
11640 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
11650 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
11660 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11670 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
11680 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
11690 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
116a0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
116b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
116c0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
116d0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
116e0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
116f0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
11700 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
11710 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
11720 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
11730 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
11740 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
11750 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
11760 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
11770 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
11780 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
11790 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
117a0 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
117b0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
117c0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
117d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
117e0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
117f0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
11800 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
11810 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
11820 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
11830 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
11840 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
11850 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
11860 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
11870 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
11880 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
11890 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
118a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
118b0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
118c0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
118d0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
118e0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
118f0 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
11900 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
11910 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
11920 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
11930 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
11940 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11950 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
11960 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
11970 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
11980 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
11990 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
119a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
119b0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
119c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
119d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
119e0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
119f0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
11a00 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
11a10 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
11a20 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
11a30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11a40 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
11a50 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
11a60 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
11a70 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
11a80 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
11a90 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
11aa0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
11ab0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
11ac0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
11ad0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
11ae0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
11af0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
11b00 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
11b10 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
11b20 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
11b30 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
11b40 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
11b50 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
11b60 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
11b70 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
11b80 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
11b90 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
11ba0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
11bb0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
11bc0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
11bd0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
11be0 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
11bf0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
11c00 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
11c10 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
11c20 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
11c30 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
11c40 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
11c50 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
11c60 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
11c70 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
11c80 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
11c90 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
11ca0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
11cb0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
11cc0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
11cd0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
11ce0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
11cf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
11d00 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
11d10 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
11d20 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
11d30 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
11d40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
11d50 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
11d60 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
11d70 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
11d80 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
11d90 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
11da0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
11db0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
11dc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
11dd0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
11de0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
11df0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
11e00 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
11e10 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
11e20 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
11e30 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
11e40 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
11e50 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
11e60 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11e70 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11e80 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
11e90 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
11ea0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
11eb0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
11ec0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
11ed0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
11ee0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
11ef0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
11f00 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
11f10 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
11f20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
11f30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
11f40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
11f50 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
11f60 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
11f70 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
11f80 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11f90 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
11fa0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
11fb0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
11fc0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
11fd0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
11fe0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
11ff0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
12000 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
12010 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
12020 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
12030 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
12040 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
12050 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
12060 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
12070 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
12080 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
12090 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
120a0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
120b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
120c0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
120d0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
120e0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
120f0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
12100 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
12110 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
12120 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
12130 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
12140 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
12150 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
12160 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
12170 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
12180 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
12190 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
121a0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
121b0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
121c0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
121d0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
121e0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
121f0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
12200 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
12210 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
12220 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
12230 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
12240 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
12250 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
12260 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
12270 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
12280 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
12290 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
122a0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
122b0 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
122c0 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
122d0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
122e0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
122f0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
12300 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
12310 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
12320 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
12330 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
12340 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
12350 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
12360 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
12370 20 5b 48 31 37 34 30 33 5d 20 5b 48 31 37 34 30   [H17403] [H1740
12380 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 63  6] [H17407].*/.c
12390 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
123a0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
123b0 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
123c0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
123d0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
123e0 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
123f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
12400 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
12410 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
12420 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
12430 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
12440 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c  ystem {H17300} <
12450 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20000>.**.** Th
12460 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75  e SQLite core  u
12470 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
12480 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
12490 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
124a0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
124b0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
124c0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
124d0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
124e0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
124f0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
12500 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
12510 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
12520 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
12530 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
12540 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
12550 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
12560 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
12570 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61  * The sqlite3_ma
12580 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
12590 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
125a0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
125b0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
125c0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
125d0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
125e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
125f0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
12600 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
12610 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
12620 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
12630 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
12640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
12650 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
12660 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
12670 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
12680 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
12690 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
126a0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
126b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
126c0 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71  **.** Calling sq
126d0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
126e0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
126f0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
12700 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
12710 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
12720 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
12730 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
12740 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
12750 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
12760 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65   The sqlite3_fre
12770 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
12780 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
12790 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
127a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
127b0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
127c0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
127d0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
127e0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
127f0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
12800 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
12810 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
12820 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
12830 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
12840 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
12850 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
12860 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
12870 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
12880 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
12890 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
128a0 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
128b0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
128c0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
128d0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
128e0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
128f0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
12900 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
12910 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
12920 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
12930 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
12940 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
12950 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  lloc()..**.** Th
12960 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
12970 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
12980 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
12990 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
129a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
129b0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
129c0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
129d0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
129e0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
129f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a00 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
12a10 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
12a20 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
12a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12a40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
12a50 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
12a60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
12a70 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
12a80 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
12a90 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
12aa0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
12ab0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
12ac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
12ad0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
12ae0 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
12af0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
12b00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12b10 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
12b20 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
12b30 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
12b40 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
12b50 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
12b60 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
12b70 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
12b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
12b90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
12ba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
12bb0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
12bc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
12be0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
12bf0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
12c00 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
12c10 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
12c20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
12c30 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
12c40 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
12c50 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
12c60 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
12c70 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
12c80 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
12c90 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
12ca0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
12cb0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
12cc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
12cd0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
12ce0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
12cf0 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
12d00 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
12d10 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
12d20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
12d30 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
12d40 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
12d50 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
12d60 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
12d70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
12d80 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
12d90 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
12da0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
12db0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
12dc0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
12dd0 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
12de0 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  ion of the memor
12df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
12e00 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74  system uses.** t
12e10 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
12e20 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
12e30 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
12e40 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12e50 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32  rary..** {H17382
12e60 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51  } However, if SQ
12e70 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12e80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12e90 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
12ea0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65  <i>NNN</i> C pre
12eb0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
12ec0 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69  (where <i>NNN</i
12ed0 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  >.** is an integ
12ee0 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  er), then SQLite
12ef0 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
12f00 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
12f10 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  st.** <i>NNN</i>
12f20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
12f30 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72  nd uses that arr
12f40 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ay for all of it
12f50 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d  s dynamic.** mem
12f60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12f70 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
12f80 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  itional memory a
12f90 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73  llocator options
12fa0 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64  .** may be added
12fb0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
12fc0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
12fd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
12fe0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
12ff0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
13000 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
13010 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
13020 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
13030 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
13040 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
13050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13060 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
13070 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
13080 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
13090 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
130a0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
130b0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
130c0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
130d0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
130e0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
130f0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
13100 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
13110 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
13120 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
13130 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
13140 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
13150 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
13160 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
13170 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
13180 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
13190 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
131a0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
131b0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
131c0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
131d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
131e0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
131f0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
13200 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
13210 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
13220 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
13230 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
13240 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
13250 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  MEM]..**.** Requ
13260 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
13270 37 33 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b  7303] [H17304] [
13280 48 31 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d  H17305] [H17306]
13290 20 5b 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31   [H17310] [H1731
132a0 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37  2] [H17315] [H17
132b0 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d  318].** [H17321]
132c0 20 5b 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32   [H17322] [H1732
132d0 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  3].**.** The poi
132e0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
132f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
13300 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
13310 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
13320 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
13330 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
13340 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
13350 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
13360 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
13370 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
13380 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13390 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
133a0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
133b0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
133c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
133d0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
133e0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
133f0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
13400 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
13410 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
13420 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
13430 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
13440 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13450 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
13460 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
13470 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
13480 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
13490 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
134a0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
134b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
134c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
134d0 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33  Statistics {H173
134e0 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a  70} <S30210>.**.
134f0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
13500 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
13510 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
13520 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
13530 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
13540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13550 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
13560 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
13570 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
13580 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
13590 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
135a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
135b0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
135c0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
135d0 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48  :.** [H17371] [H
135e0 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34 5d 20  17373] [H17374] 
135f0 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69  [H17375].*/.sqli
13600 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
13610 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
13620 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
13630 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
13640 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
13650 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
13660 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
13670 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
13680 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37  r Generator {H17
13690 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  390} <S20000>.**
136a0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
136b0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
136c0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
136d0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
136e0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
136f0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
13700 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
13710 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
13720 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
13730 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
13740 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
13750 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
13760 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
13770 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
13780 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
13790 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
137a0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
137b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
137c0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
137d0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
137e0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
137f0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
13800 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
13810 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
13820 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
13830 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
13840 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
13850 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
13860 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
13870 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
13880 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
13890 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
138a0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
138b0 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
138c0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
138d0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
138e0 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
138f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
13900 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
13910 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
13920 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
13930 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
13940 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
13950 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
13960 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
13970 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
13980 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
13990 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
139a0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
139b0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
139c0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
139d0 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a  .** [H17392].*/.
139e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
139f0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
13a00 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
13a10 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
13a20 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
13a30 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
13a40 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e  H12500} <S70100>
13a50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
13a60 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
13a70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
13a80 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
13a90 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
13aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
13ab0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
13ac0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
13ad0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
13ae0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
13af0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
13b00 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
13b10 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
13b20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13b30 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
13b40 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
13b50 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
13b60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13b70 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
13b80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13b90 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
13ba0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
13bb0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
13bc0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
13bd0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
13be0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
13bf0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
13c00 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
13c10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
13c20 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
13c30 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
13c40 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
13c50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
13c60 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
13c70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13c80 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
13c90 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
13ca0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
13cb0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
13cc0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
13cd0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
13ce0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
13cf0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
13d00 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
13d10 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
13d20 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
13d30 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
13d40 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
13d50 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74   an error.  If t
13d60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
13d70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
13d80 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
13d90 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
13da0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
13db0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
13dc0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
13dd0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
13de0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
13df0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
13e00 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
13e10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
13e20 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
13e30 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
13e40 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
13e50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
13e60 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
13e70 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
13e80 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
13e90 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
13ea0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
13eb0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
13ec0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
13ed0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
13ee0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
13ef0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
13f00 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
13f10 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
13f20 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
13f30 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
13f40 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
13f50 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65   denied.  If the
13f60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
13f70 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
13f80 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
13f90 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
13fa0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
13fb0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
13fc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
13fd0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
13fe0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
13ff0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
14000 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
14010 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
14020 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
14030 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
14040 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
14050 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
14060 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
14070 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
14080 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14090 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
140a0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
140b0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
140c0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
140d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
140e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
140f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
14100 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
14110 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
14120 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
14130 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
14140 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
14150 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e  rface. The secon
14160 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
14170 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
14180 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
14190 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
141a0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
141b0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
141c0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
141d0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
141e0 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72  d. The third thr
141f0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
14200 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
14210 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
14220 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
14230 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
14240 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
14250 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
14260 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
14270 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
14280 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
14290 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
142a0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
142b0 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
142c0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
142d0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
142e0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
142f0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
14300 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
14310 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
14320 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
14330 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
14340 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
14350 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
14360 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
14370 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
14380 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
14390 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
143a0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
143b0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
143c0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
143d0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
143e0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
143f0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
14400 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
14410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
14420 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
14430 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
14440 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
14450 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
14460 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
14470 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
14480 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
14490 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
144a0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
144b0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
144c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
144d0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
144e0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
144f0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
14500 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
14510 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
14520 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
14530 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
14540 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
14550 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
14560 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
14570 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
14580 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
14590 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
145a0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
145b0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
145c0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
145d0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
145e0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
145f0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
14600 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
14610 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
14620 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
14630 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
14640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14650 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
14660 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
14670 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
14680 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
14690 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
146a0 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
146b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
146c0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
146d0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
146e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
146f0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
14700 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
14710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
14720 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
14730 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
14740 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
14750 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14760 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
14770 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
14780 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
14790 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
147a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
147b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
147c0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
147d0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
147e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
147f0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
14800 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
14810 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
14820 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  .** When [sqlite
14830 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
14840 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
14850 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
14860 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
14870 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70   might be reprep
14880 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
14890 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
148a0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
148b0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
148c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
148d0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
148e0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
148f0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
14900 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
14910 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
14920 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
14930 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ()]..**.** Note 
14940 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
14950 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
14960 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
14970 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14980 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
14990 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
149a0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
149b0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
149c0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
149d0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
149e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
149f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
14a00 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d 20  ts:.** [H12501] 
14a10 5b 48 31 32 35 30 32 5d 20 5b 48 31 32 35 30 33  [H12502] [H12503
14a20 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48 31 32 35  ] [H12504] [H125
14a30 30 35 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48 31  05] [H12506] [H1
14a40 32 35 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a 2a  2507] [H12510].*
14a50 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48 31 32 35  * [H12511] [H125
14a60 31 32 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48 31  12] [H12520] [H1
14a70 32 35 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a 2a  2521] [H12522].*
14a80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
14a90 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
14aa0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
14ab0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
14ac0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
14ad0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
14ae0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
14af0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
14b00 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
14b10 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
14b20 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
14b30 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32  es {H12590} <H12
14b40 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
14b50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
14b60 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
14b70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
14b80 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
14b90 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
14ba0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
14bb0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
14bc0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
14bd0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
14be0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
14bf0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
14c00 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
14c10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14c20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
14c30 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
14c40 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
14c50 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
14c60 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64  formation..*/.#d
14c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
14c80 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
14c90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14ca0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
14cb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14cc0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
14cd0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
14ce0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
14cf0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
14d00 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
14d10 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
14d20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31  Action Codes {H1
14d30 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a  2550} <H12500>.*
14d40 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
14d50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14d60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
14d70 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
14d80 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
14d90 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
14da0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
14db0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
14dc0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
14dd0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
14de0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
14df0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
14e00 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
14e10 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
14e20 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
14e30 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
14e40 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
14e50 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
14e60 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
14e70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
14e80 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
14e90 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
14ea0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
14eb0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
14ec0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
14ed0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
14ee0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
14ef0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
14f00 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
14f10 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
14f20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
14f30 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
14f40 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
14f50 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
14f60 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
14f70 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
14f80 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35  arameter.  The 5
14f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
14fa0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
14fb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
14fc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
14fd0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
14fe0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
14ff0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
15000 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
15010 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
15020 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
15030 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
15040 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
15050 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
15060 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
15070 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
15080 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
15090 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
150a0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
150b0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
150c0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
150d0 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  de..**.** Requir
150e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
150f0 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48 31  51] [H12552] [H1
15100 32 35 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a 2a  2553] [H12554].*
15110 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
15120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
15140 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
15150 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
15160 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15170 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
15180 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
15190 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
151a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
151b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
151c0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
151d0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
151e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
151f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15210 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
15220 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
15230 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
15240 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
15250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15260 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
15270 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
15280 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
15290 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
152a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
152b0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
152c0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
152d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
152e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
152f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
15300 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
15310 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
15320 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
15330 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15340 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
15350 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
15360 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
15370 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
15380 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15390 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
153a0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
153b0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
153c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
153d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
153e0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
153f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
15400 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15410 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15420 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15430 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
15440 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
15450 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
15460 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15470 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15480 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
15490 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
154a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
154b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
154c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
154d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
154e0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
154f0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
15500 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
15510 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15520 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
15530 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
15540 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15550 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15560 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15570 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
15580 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
15590 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
155a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
155b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
155c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
155d0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
155e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
155f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15600 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15610 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
15620 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
15630 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
15640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15660 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
15670 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
15680 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
15690 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
156a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
156b0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
156c0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
156d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
156e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
156f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
15700 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
15710 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
15720 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
15730 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
15740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
15750 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
15760 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
15770 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
15780 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
15790 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
157a0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
157b0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
157c0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
157d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
157e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
157f0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
15800 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
15810 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
15820 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15830 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
15840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
15850 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
15860 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
15870 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
15880 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
15890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
158a0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
158b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
158c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
158d0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
158e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
158f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
15900 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
15910 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15920 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
15930 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
15940 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
15950 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
15960 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15970 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
15980 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
15990 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
159a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
159b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
159c0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
159d0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
159e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
159f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15a00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15a10 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
15a20 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
15a30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15a40 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
15a50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15a60 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
15a70 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
15a80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15a90 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
15aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15ab0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
15ac0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
15ad0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
15ae0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
15af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b00 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
15b10 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
15b20 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
15b30 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
15b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15b50 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
15b60 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
15b70 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
15b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15b90 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
15ba0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
15bb0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
15bc0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
15bd0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
15be0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
15bf0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
15c00 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
15c10 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
15c20 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
15c30 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
15c40 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
15c50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
15c60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
15c70 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
15c80 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
15c90 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
15ca0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
15cb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
15cc0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
15cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15ce0 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
15cf0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
15d00 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
15d10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
15d20 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
15d30 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
15d40 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
15d50 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
15d60 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
15d70 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
15d80 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
15d90 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
15da0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
15db0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
15dc0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
15dd0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
15de0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
15df0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
15e00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
15e10 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
15e20 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
15e30 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
15e40 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
15e50 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
15e60 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
15e70 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
15e80 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
15e90 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
15ea0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
15eb0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
15ec0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
15ed0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
15ee0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52   to run..**.** R
15ef0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
15f00 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 32 38 32  [H12281] [H12282
15f10 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 31 32 32  ] [H12283] [H122
15f20 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48 31  84] [H12285] [H1
15f30 32 32 38 37 5d 20 5b 48 31 32 32 38 38 5d 20 5b  2287] [H12288] [
15f40 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32 32  H12289].** [H122
15f50 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  90].*/.SQLITE_EX
15f60 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
15f70 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
15f80 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
15f90 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
15fa0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
15fb0 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
15fc0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
15fd0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
15fe0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
15ff0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
16000 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
16010 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
16020 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
16030 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
16040 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b  ress Callbacks {
16050 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e  H12910} <S60400>
16060 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
16070 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
16080 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16090 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
160a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
160b0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
160c0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
160d0 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
160e0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
160f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
16100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
16110 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
16120 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
16130 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
16140 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
16150 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
16160 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
16170 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
16180 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
16190 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
161a0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
161b0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
161c0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
161d0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
161e0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
161f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
16200 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
16210 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
16220 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
16230 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
16240 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  s handler must n
16250 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
16260 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
16270 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
16280 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
16290 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
162a0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
162b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
162c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
162d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
162e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
162f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
16300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
16310 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
16320 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
16330 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
16340 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
16350 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d 20  ts:.** [H12911] 
16360 5b 48 31 32 39 31 32 5d 20 5b 48 31 32 39 31 33  [H12912] [H12913
16370 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48 31 32 39  ] [H12914] [H129
16380 31 35 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48 31  15] [H12916] [H1
16390 32 39 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a 2a  2917] [H12918].*
163a0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
163b0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
163c0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
163d0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
163e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
163f0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
16400 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
16410 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32   Connection {H12
16420 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a  700} <S40200>.**
16430 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
16440 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
16450 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
16460 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
16470 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
16480 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
16490 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
164a0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
164b0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
164c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
164d0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
164e0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
164f0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
16500 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
16510 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
16520 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61  _open16(). A [da
16530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16540 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
16550 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
16560 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
16570 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
16580 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
16590 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
165a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
165b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
165c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
165d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
165e0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
165f0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
16600 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
16610 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
16620 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
16630 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66  3].** object. If
16640 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
16650 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
16660 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
16670 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
16680 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
16690 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
166a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
166b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  e] is returned. 
166c0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
166d0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
166e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
166f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
16700 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
16710 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
16720 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
16730 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
16740 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  r..**.** The def
16750 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
16760 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
16770 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
16780 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
16790 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
167a0 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
167b0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
167c0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
167d0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
167e0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
167f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
16800 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
16810 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
16820 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
16830 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
16840 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
16850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16860 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
16870 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
16880 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
16890 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
168a0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
168b0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
168c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
168d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
168e0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
168f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
16900 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
16910 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
16920 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
16930 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
16940 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
16950 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
16960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16970 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
16980 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65  rameter can take
16990 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
169a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
169b0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
169c0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
169d0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
169e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
169f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
16a00 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a  LLMUTEX] flags:.
16a10 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16a20 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
16a30 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
16a40 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
16a50 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
16a60 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
16a70 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
16a80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
16a90 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
16aa0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
16ab0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16ac0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
16ad0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
16ae0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
16af0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
16b00 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
16b10 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
16b20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
16b30 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
16b40 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
16b50 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
16b60 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
16b70 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
16b80 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
16b90 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
16ba0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
16bb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
16bc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
16bd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
16be0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
16bf0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
16c00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
16c10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
16c20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
16c30 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
16c40 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
16c50 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
16c60 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
16c70 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
16c80 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
16c90 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
16ca0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
16cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
16cc0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
16cd0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
16ce0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
16cf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
16d00 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
16d10 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
16d20 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
16d30 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
16d40 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
16d50 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
16d60 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16d70 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f  _OPEN_NOMUTEX] o
16d80 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  r [SQLITE_OPEN_F
16d90 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c  ULLMUTEX] flags,
16da0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
16db0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
16dc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
16dd0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
16de0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
16df0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
16e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16e10 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
16e20 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
16e30 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
16e40 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
16e50 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
16e60 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
16e70 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
16e80 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
16e90 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
16ea0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
16eb0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
16ec0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
16ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16ee0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
16ef0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
16f00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
16f10 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
16f20 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
16f30 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
16f40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
16f50 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  tart-time..**.**
16f60 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
16f70 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
16f80 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
16f90 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
16fa0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
16fb0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
16fc0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
16fd0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
16fe0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
16ff0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
17000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17010 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
17020 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
17030 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
17040 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
17050 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
17060 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
17070 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
17080 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
17090 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
170a0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
170b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
170c0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
170d0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
170e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
170f0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
17100 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
17110 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
17120 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
17130 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
17140 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
17150 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
17160 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
17170 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
17180 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
17190 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
171a0 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
171b0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
171c0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
171d0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
171e0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
171f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17200 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
17210 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
17220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
17240 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
17250 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
17260 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
17270 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
17280 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
17290 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
172a0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
172b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
172c0 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66  d use.  If the f
172d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
172e0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
172f0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
17300 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
17310 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
17320 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
17330 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
17340 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
17350 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
17360 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
17370 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
17380 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
17390 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
173a0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
173b0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
173c0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
173d0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
173e0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
173f0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
17400 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
17410 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
17420 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
17430 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
17440 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
17450 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
17460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
17470 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
17480 3a 0a 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48  :.** [H12701] [H
17490 31 32 37 30 32 5d 20 5b 48 31 32 37 30 33 5d 20  12702] [H12703] 
174a0 5b 48 31 32 37 30 34 5d 20 5b 48 31 32 37 30 36  [H12704] [H12706
174b0 5d 20 5b 48 31 32 37 30 37 5d 20 5b 48 31 32 37  ] [H12707] [H127
174c0 30 39 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20  09] [H12711].** 
174d0 5b 48 31 32 37 31 32 5d 20 5b 48 31 32 37 31 33  [H12712] [H12713
174e0 5d 20 5b 48 31 32 37 31 34 5d 20 5b 48 31 32 37  ] [H12714] [H127
174f0 31 37 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48 31  17] [H12719] [H1
17500 32 37 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a  2721] [H12723].*
17510 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
17520 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
17530 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
17540 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
17550 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
17560 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
17570 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
17580 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
17590 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
175a0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
175b0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
175c0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
175d0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
175e0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
175f0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
17600 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
17610 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
17620 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
17630 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
17640 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
17650 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
17660 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
17670 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
17680 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
17690 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
176a0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
176b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
176c0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
176d0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
176e0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
176f0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
17700 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
17710 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
17720 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
17730 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
17740 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
17750 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
17760 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17770 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
17780 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
17790 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
177a0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
177b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
177c0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
177d0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
177e0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
177f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17800 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
17810 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
17820 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
17830 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
17840 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
17850 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
17860 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
17870 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
17880 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78    The sqlite3_ex
17890 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
178a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
178b0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
178c0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
178d0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
178e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
178f0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
17900 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
17910 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
17920 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  sabled..**.** Th
17930 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
17940 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
17950 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
17960 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
17970 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
17980 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
17990 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
179a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
179b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
179c0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
179d0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
179e0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
179f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
17a00 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
17a10 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
17a20 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
17a30 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
17a40 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
17a50 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
17a60 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
17a70 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
17a80 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
17a90 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
17aa0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
17ab0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
17ac0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
17ad0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
17ae0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
17af0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
17b00 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
17b10 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
17b20 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
17b30 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
17b40 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
17b50 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
17b60 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
17b70 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
17b80 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
17b90 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
17ba0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
17bb0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
17bc0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
17bd0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
17be0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
17bf0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
17c00 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
17c10 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
17c20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
17c30 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
17c40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17c50 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
17c60 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
17c70 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
17c80 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
17c90 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
17ca0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
17cb0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
17cc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
17cd0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
17ce0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
17cf0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
17d00 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
17d10 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
17d20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
17d30 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
17d40 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
17d50 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
17d60 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
17d70 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
17d80 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
17d90 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
17da0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
17db0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
17dc0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
17dd0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
17de0 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  e set..**.** Req
17df0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
17e00 31 32 38 30 31 5d 20 5b 48 31 32 38 30 32 5d 20  12801] [H12802] 
17e10 5b 48 31 32 38 30 33 5d 20 5b 48 31 32 38 30 37  [H12803] [H12807
17e20 5d 20 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 38  ] [H12808] [H128
17e30 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  09].*/.int sqlit
17e40 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
17e50 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
17e60 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
17e70 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
17e80 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
17e90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
17ea0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
17eb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
17ec0 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
17ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17ee0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
17ef0 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d   Object {H13000}
17f00 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59   <H13010>.** KEY
17f10 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
17f20 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
17f30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
17f40 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
17f50 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
17f60 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
17f70 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
17f80 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
17f90 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
17fa0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
17fb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17fc0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
17fd0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
17fe0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
17ff0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
18000 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
18010 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
18020 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
18030 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
18040 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
18050 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
18060 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
18070 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18080 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
18090 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
180a0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
180b0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
180c0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
180d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
180e0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
180f0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
18100 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
18110 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
18120 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
18130 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
18140 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
18150 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
18160 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
18170 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
18180 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
18190 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
181a0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
181b0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
181c0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
181d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
181e0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
181f0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
18200 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
18210 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
18220 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
18230 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
18240 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
18250 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
18260 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
18270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18280 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
18290 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30   {H12760} <S2060
182a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
182b0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
182c0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
182d0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
182e0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
182f0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
18300 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
18310 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
18320 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
18330 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
18340 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
18350 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
18360 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
18370 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
18380 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
18390 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
183a0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
183b0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
183c0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
183d0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
183e0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
183f0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
18400 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
18410 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
18420 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
18430 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
18440 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
18450 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
18460 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
18470 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
18480 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
18490 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
184a0 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
184b0 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
184c0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
184d0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
184e0 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d  .** set by a com
184f0 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70  pile-time C prep
18500 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e  rocessor macro n
18510 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  amed .** [limits
18520 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59   | SQLITE_MAX_XY
18530 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  Z]..** (The "_LI
18540 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
18550 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
18560 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74  "_MAX_".).** Att
18570 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
18580 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
18590 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
185a0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
185b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
185c0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
185d0 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75   limit..**.** Ru
185e0 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n time limits ar
185f0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
18600 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
18610 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
18620 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
18630 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
18640 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
18650 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
18660 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
18670 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
18680 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
18690 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
186a0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
186b0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
186c0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
186d0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
186e0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
186f0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
18700 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
18710 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
18720 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
18730 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
18740 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
18750 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
18760 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
18770 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
18780 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
18790 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
187a0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
187b0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
187c0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
187d0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
187e0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
187f0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
18800 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
18810 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
18820 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
18830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
18840 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
18850 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
18860 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
18870 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
18880 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
18890 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
188a0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
188b0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
188c0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
188d0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
188e0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
188f0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
18900 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
18910 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
18920 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
18930 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52  eleases..**.** R
18940 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
18950 5b 48 31 32 37 36 32 5d 20 5b 48 31 32 37 36 36  [H12762] [H12766
18960 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e  ] [H12769].*/.in
18970 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
18980 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
18990 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
189a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
189b0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
189c0 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39  ategories {H1279
189d0 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b  0} <H12760>.** K
189e0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
189f0 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74  category} {limit
18a00 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
18a10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
18a20 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
18a30 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
18a40 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
18a50 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
18a60 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
18a70 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
18a80 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
18a90 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
18aa0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
18ab0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
18ac0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
18ad0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
18ae0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
18af0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
18b00 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
18b10 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
18b20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
18b30 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
18b40 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
18b50 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
18b60 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
18b70 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
18b80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18b90 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
18ba0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18bb0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
18bc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
18bd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
18bf0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
18c00 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18c10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
18c20 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
18c30 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
18c40 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
18c50 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
18c60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18c70 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
18c80 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
18c90 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
18ca0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
18cb0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18cc0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
18cd0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
18ce0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
18cf0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
18d00 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
18d10 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ession.</dd>.**.
18d20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18d30 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
18d40 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
18d50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18d60 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
18d70 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
18d80 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
18d90 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18da0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
18db0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18dc0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18dd0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
18de0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
18df0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
18e00 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
18e10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18e20 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
18e30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
18e40 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
18e50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18e60 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
18e70 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
18e80 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
18e90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18ea0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
18eb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18ec0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
18ed0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
18ee0 20 64 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64   databases].</dd
18ef0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18f00 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
18f10 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
18f20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18f30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
18f40 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
18f50 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
18f60 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
18f70 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a  perators.</dd>.*
18f80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18f90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
18fa0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
18fb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18fc0 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
18fd0 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
18fe0 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
18ff0 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
19000 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
19010 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
19020 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
19030 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
19040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
19050 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
19060 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
19070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
19080 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
19090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
190a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
190b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
190c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
190d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
190f0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
19100 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
19110 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
19120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19130 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
19140 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
19150 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
19160 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
19170 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
19180 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
19190 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
191a0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
191b0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
191c0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
191d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
191e0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
191f0 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41       9../*.** CA
19200 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
19210 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
19220 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30  nt {H13010} <S10
19230 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000>.** KEYWORDS
19240 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
19250 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
19260 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
19270 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
19280 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
19290 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
192a0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
192b0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
192c0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
192d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
192e0 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
192f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
19300 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
19310 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
19320 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
19330 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
19340 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
19350 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
19360 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
19370 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
19380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
19390 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
193a0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
193b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
193c0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
193d0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
193e0 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
193f0 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
19400 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
19410 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
19420 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
19430 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19440 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
19450 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
19460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19470 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
19480 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
19490 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
194a0 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
194b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
194c0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
194d0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
194e0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
194f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
19500 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f  . If nByte is no
19510 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
19520 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
19530 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
19540 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
19550 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
19560 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
19570 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
19580 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
19590 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
195a0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
195b0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
195c0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
195d0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
195e0 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
195f0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
19600 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
19610 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
19620 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
19630 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
19640 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
19650 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
19660 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
19670 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
19680 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
19690 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
196a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
196b0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
196c0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
196d0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
196e0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
196f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54  es..**.** If pzT
19700 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
19710 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
19720 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
19730 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
19740 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
19750 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
19760 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
19770 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
19780 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
19790 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
197a0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
197b0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
197c0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
197d0 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
197e0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
197f0 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  * *ppStmt is lef
19800 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
19810 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
19820 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19830 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
19840 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
19850 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49  ite3_step()].  I
19860 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
19870 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
19880 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
19890 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
198a0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
198b0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
198c0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
198d0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
198e0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
198f0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
19900 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
19910 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
19920 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
19930 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
19940 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
19950 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
19960 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
19970 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
19980 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
19990 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
199a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
199b0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
199c0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
199d0 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ned, otherwise a
199e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
199f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
19a00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
19a10 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
19a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19a30 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
19a40 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
19a50 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
19a60 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
19a70 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
19a80 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
19a90 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
19aa0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
19ab0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
19ac0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
19ad0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
19ae0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
19af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
19b00 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
19b10 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
19b20 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
19b30 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
19b40 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
19b50 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
19b60 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
19b70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
19b80 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
19b90 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
19ba0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
19bb0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
19bc0 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
19bd0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
19be0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
19bf0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
19c00 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
19c10 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
19c20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
19c30 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
19c40 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
19c50 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
19c60 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
19c70 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
19c80 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
19c90 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
19ca0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
19cb0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
19cc0 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
19cd0 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
19ce0 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
19cf0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19d00 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
19d10 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
19d20 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c  y behavior, [SQL
19d30 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a  ITE_SCHEMA] is.*
19d40 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  * now a fatal er
19d50 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73  ror.  Calling [s
19d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19d70 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
19d80 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
19d90 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
19da0 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
19db0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
19dc0 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
19dd0 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
19de0 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
19df0 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
19e00 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
19e10 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
19e20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20  <li>.** When an 
19e30 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
19e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
19e50 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
19e60 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
19e70 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
19e80 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
19e90 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20  or codes].  The 
19ea0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
19eb0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
19ec0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
19ed0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
19ee0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
19ef0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
19f00 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77  ode.** and you w
19f10 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
19f20 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
19f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
19f40 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  t()] in order.**
19f50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
19f60 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
19f70 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
19f80 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
19f90 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
19fa0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
19fb0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
19fc0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
19fd0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
19fe0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
19ff0 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  >.**.** Requirem
1a000 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 30 31 31  ents:.** [H13011
1a010 5d 20 5b 48 31 33 30 31 32 5d 20 5b 48 31 33 30  ] [H13012] [H130
1a020 31 33 5d 20 5b 48 31 33 30 31 34 5d 20 5b 48 31  13] [H13014] [H1
1a030 33 30 31 35 5d 20 5b 48 31 33 30 31 36 5d 20 5b  3015] [H13016] [
1a040 48 31 33 30 31 39 5d 20 5b 48 31 33 30 32 31 5d  H13019] [H13021]
1a050 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .**.*/.int sqlit
1a060 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1a070 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a080 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a090 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a0a0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1a0b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a0c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1a0d0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1a0e0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1a0f0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1a100 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1a110 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1a120 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1a130 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1a140 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1a150 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1a160 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1a170 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1a180 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1a190 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1a1a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a1b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1a1c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1a1d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1a1e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a1f0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1a200 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1a210 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1a220 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a230 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a240 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a250 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a260 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a270 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a280 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a290 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1a2a0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1a2b0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a2c0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a2d0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a2e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a2f0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1a300 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1a310 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1a320 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1a330 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1a340 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1a350 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1a360 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1a370 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1a380 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1a390 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1a3a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1a3b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1a3c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1a3d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1a3e0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1a3f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1a400 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1a410 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1a420 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a430 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1a440 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1a450 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1a460 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1a470 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1a480 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1a490 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1a4a0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1a4b0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1a4c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1a4d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1a4e0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1a4f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1a500 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1a510 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1a520 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1a530 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1a540 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1a550 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1a560 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1a570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a580 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1a590 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30  ment SQL {H13100
1a5a0 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H13000>.**.**
1a5b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1a5c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
1a5d0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
1a5e0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
1a5f0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
1a600 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
1a610 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1a620 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
1a630 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
1a640 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1a650 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1a660 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1a670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a680 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1a690 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1a6a0 20 5b 48 31 33 31 30 31 5d 20 5b 48 31 33 31 30   [H13101] [H1310
1a6b0 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a 2f 0a 63  2] [H13103].*/.c
1a6c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1a6d0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
1a6e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1a6f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
1a700 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
1a710 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31  Value Object {H1
1a720 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5000} <S20200>.*
1a730 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
1a740 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a750 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
1a760 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1a770 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
1a780 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
1a790 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
1a7a0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
1a7b0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
1a7c0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
1a7d0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
1a7e0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1a7f0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
1a800 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
1a810 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
1a820 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
1a830 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
1a840 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
1a850 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
1a860 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
1a870 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
1a880 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
1a890 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1a8a0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
1a8b0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
1a8c0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
1a8d0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
1a8e0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
1a8f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a900 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
1a910 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
1a920 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
1a930 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
1a940 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a950 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
1a960 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1a970 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
1a980 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
1a990 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
1a9a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
1a9b0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
1a9c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a9d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
1a9e0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
1a9f0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
1aa00 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
1aa10 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
1aa20 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
1aa30 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
1aa40 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
1aa50 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1aa60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
1aa70 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
1aa80 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
1aa90 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1aaa0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
1aab0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1aac0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
1aad0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
1aae0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
1aaf0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
1ab00 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
1ab10 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
1ab20 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
1ab30 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
1ab40 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
1ab50 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
1ab60 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
1ab70 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
1ab80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
1ab90 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
1aba0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
1abb0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
1abc0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1abd0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1abe0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1abf0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
1ac00 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
1ac10 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
1ac20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
1ac30 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
1ac40 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
1ac50 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1ac60 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
1ac70 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
1ac80 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1ac90 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  en between prote
1aca0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1acb0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1acc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
1acd0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
1ace0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
1acf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1ad00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1ad10 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1ad20 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1ad30 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1ad40 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
1ad50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1ad60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
1ad70 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1ad80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1ad90 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
1ada0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
1adb0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
1adc0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
1add0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
1ade0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1adf0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
1ae00 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
1ae10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1ae20 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
1ae30 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1ae40 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
1ae50 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
1ae60 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
1ae70 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
1ae80 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
1ae90 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
1aea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1aeb0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
1aec0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
1aed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
1aee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1aef0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
1af00 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30  ext Object {H160
1af10 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  01} <S20200>.**.
1af20 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
1af30 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
1af40 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
1af50 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
1af60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
1af70 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
1af80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1af90 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
1afa0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
1afb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1afc0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
1afd0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1afe0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
1aff0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1b000 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1b010 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b020 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1b030 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
1b040 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
1b050 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1b060 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
1b070 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
1b080 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1b090 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
1b0a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
1b0b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
1b0c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
1b0d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
1b0e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
1b0f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
1b100 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
1b110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1b120 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1b130 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1b140 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1b150 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
1b160 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
1b170 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30  tatements {H1350
1b180 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b  0} <S70300>.** K
1b190 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
1b1a0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
1b1b0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
1b1c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1b1d0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1b1e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
1b1f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
1b200 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
1b210 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
1b220 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
1b230 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
1b240 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1b250 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
1b260 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
1b270 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
1b280 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 6f  [parameter] in o
1b290 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d  ne of these form
1b2a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1b2b0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1b2c0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1b2d0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1b2e0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1b2f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1b300 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
1b310 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
1b320 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
1b330 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
1b340 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61   and VVV is an a
1b350 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72  lpha-numeric par
1b360 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65  ameter name. The
1b370 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
1b380 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
1b390 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
1b3a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1b3b0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
1b3c0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
1b3d0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
1b3e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1b3f0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
1b400 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
1b410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b420 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1b430 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1b440 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
1b450 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1b460 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1b470 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1b480 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1b490 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b4a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
1b4b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1b4c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1b4d0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
1b4e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
1b4f0 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66   set..** The lef
1b500 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1b510 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1b520 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
1b530 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
1b540 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
1b550 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
1b560 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
1b570 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
1b580 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
1b590 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
1b5a0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
1b5b0 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e  rence..** The in
1b5c0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
1b5d0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
1b5e0 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
1b5f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b600 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1b610 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
1b620 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
1b630 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
1b640 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
1b650 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
1b660 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
1b670 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
1b680 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
1b690 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1b6a0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
1b6b0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1b6c0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
1b6d0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
1b6e0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
1b6f0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1b700 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1b710 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1b720 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72  **.** In those r
1b730 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
1b740 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
1b750 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
1b760 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1b770 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1b780 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
1b790 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
1b7a0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1b7b0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
1b7c0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
1b7d0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
1b7e0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
1b7f0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
1b800 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1b810 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1b820 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1b830 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1b840 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1b850 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1b860 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1b870 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
1b880 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1b890 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1b8a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1b8b0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1b8c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1b8d0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1b8e0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1b8f0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1b900 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1b910 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1b920 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68  d with it. If th
1b930 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1b940 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
1b950 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
1b960 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
1b970 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
1b980 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
1b990 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
1b9a0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
1b9b0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
1b9c0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
1b9d0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66  d..** If the fif
1b9e0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
1b9f0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
1ba00 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
1ba10 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
1ba20 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
1ba30 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
1ba40 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
1ba50 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
1ba60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1ba70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
1ba80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ba90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1baa0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
1bab0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
1bac0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
1bad0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
1bae0 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
1baf0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
1bb00 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
1bb10 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
1bb20 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
1bb30 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
1bb40 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
1bb50 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
1bb60 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
1bb70 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
1bb80 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
1bb90 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
1bba0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
1bbb0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1bbc0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
1bbd0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
1bbe0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
1bbf0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1bc00 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1bc10 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1bc20 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1bc30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bc40 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1bc50 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1bc60 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71  led after.** [sq
1bc70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bc80 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72  ()] (and its var
1bc90 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74  iants) or [sqlit
1bca0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a  e3_reset()] and.
1bcb0 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  ** before [sqlit
1bcc0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42  e3_step()]..** B
1bcd0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
1bce0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
1bcf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1bd00 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62   routine..** Unb
1bd10 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
1bd20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1bd30 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  as NULL..**.** T
1bd40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1bd50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1bd60 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
1bd70 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
1bd80 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
1bd90 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45   wrong.  [SQLITE
1bda0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1bdb0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1bdc0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1bdd0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1bde0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
1bdf0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
1be00 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
1be10 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1be20 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1be30 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1be40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1be50 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1be60 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1be70 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1be80 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1be90 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1bea0 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1beb0 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1bec0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1bed0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1bee0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1bef0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1bf00 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1bf10 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1bf20 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1bf30 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1bf40 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1bf50 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1bf60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1bf70 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1bf80 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1bf90 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1bfa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bfb0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1bfc0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1bfd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1bfe0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1bff0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
1c000 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1c010 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1c020 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1c030 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d 20 5b 48  :.** [H13506] [H
1c040 31 33 35 30 39 5d 20 5b 48 31 33 35 31 32 5d 20  13509] [H13512] 
1c050 5b 48 31 33 35 31 35 5d 20 5b 48 31 33 35 31 38  [H13515] [H13518
1c060 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48 31 33 35  ] [H13521] [H135
1c070 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a 2a 2a 20  24] [H13527].** 
1c080 5b 48 31 33 35 33 30 5d 20 5b 48 31 33 35 33 33  [H13530] [H13533
1c090 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48 31 33 35  ] [H13536] [H135
1c0a0 33 39 5d 20 5b 48 31 33 35 34 32 5d 20 5b 48 31  39] [H13542] [H1
1c0b0 33 35 34 35 5d 20 5b 48 31 33 35 34 38 5d 20 5b  3545] [H13548] [
1c0c0 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e  H13551].**.*/.in
1c0d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1c0e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1c0f0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1c100 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1c110 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1c120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1c130 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1c140 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1c150 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1c160 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1c170 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1c180 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1c190 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1c1a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1c1b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1c1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1c1d0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1c1e0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1c1f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1c200 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1c210 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1c220 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1c230 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1c240 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1c250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1c260 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1c270 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1c280 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1c290 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1c2a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1c2b0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1c2c0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1c2d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1c2e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c2f0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1c300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1c310 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1c320 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
1c330 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
1c340 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
1c350 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
1c360 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
1c370 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
1c380 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
1c390 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
1c3a0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
1c3b0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
1c3c0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
1c3d0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
1c3e0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
1c3f0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
1c400 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1c410 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
1c420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1c430 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
1c440 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
1c450 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
1c460 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1c470 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
1c480 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
1c490 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
1c4a0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
1c4b0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
1c4c0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
1c4d0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
1c4e0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
1c4f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
1c500 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
1c510 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
1c520 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
1c530 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
1c540 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
1c550 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
1c560 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1c570 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1c580 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1c590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1c5a0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1c5b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1c5c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1c5d0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  dex()]..**.** Re
1c5e0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1c5f0 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73  H13601].*/.int s
1c600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1c610 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1c620 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1c630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1c640 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1c650 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c  meter {H13620} <
1c660 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
1c670 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1c680 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1c690 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1c6a0 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
1c6b0 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
1c6c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c6d0 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
1c6e0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1c6f0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1c700 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1c710 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
1c720 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
1c730 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
1c740 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1c750 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1c760 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1c770 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
1c780 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
1c790 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
1c7a0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
1c7b0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
1c7c0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
1c7d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1c7e0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
1c7f0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
1c800 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
1c810 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
1c820 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
1c830 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
1c840 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
1c850 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
1c860 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
1c870 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
1c880 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
1c890 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
1c8a0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
1c8b0 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
1c8c0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
1c8d0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
1c8e0 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
1c8f0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
1c900 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
1c910 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
1c920 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
1c930 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
1c940 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
1c950 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
1c960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c970 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
1c980 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1c990 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
1c9a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1c9b0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1c9c0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1c9d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1c9e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
1c9f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1ca00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1ca10 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  dex()]..**.** Re
1ca20 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1ca30 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13621].*/.const
1ca40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
1ca50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1ca60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1ca70 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
1ca80 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
1ca90 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
1caa0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
1cab0 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
1cac0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
1cad0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1cae0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1caf0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
1cb00 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
1cb10 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
1cb20 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
1cb30 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
1cb40 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1cb50 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1cb60 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
1cb70 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
1cb80 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
1cb90 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
1cba0 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
1cbb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
1cbc0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
1cbd0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
1cbe0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1cbf0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
1cc00 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
1cc10 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
1cc20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1cc30 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1cc40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1cc50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1cc60 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1cc70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1cc80 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1cc90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1cca0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ccb0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1ccc0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1ccd0 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74   [H13641].*/.int
1cce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1ccf0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
1cd00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
1cd10 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
1cd20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd30 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
1cd40 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
1cd50 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed Statement {H1
1cd60 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3660} <S70300>.*
1cd70 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
1cd80 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
1cd90 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
1cda0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
1cdb0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
1cdc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1cdd0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
1cde0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1cdf0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65  atement]..** Use
1ce00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
1ce10 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
1ce20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
1ce30 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  LL..**.** Requir
1ce40 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1ce50 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  61].*/.int sqlit
1ce60 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
1ce70 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
1ce80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ce90 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
1cea0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
1ceb0 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53   Set {H13710} <S
1cec0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  10700>.**.** Ret
1ced0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
1cee0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
1cef0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
1cf00 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
1cf10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cf20 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
1cf30 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
1cf40 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
1cf50 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
1cf60 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
1cf70 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
1cf80 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
1cf90 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1cfa0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 31 5d  nts:.** [H13711]
1cfb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cfc0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
1cfd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1cfe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cff0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
1d000 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1d010 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30   {H13720} <S1070
1d020 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1d030 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1d040 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
1d050 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
1d060 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
1d070 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
1d080 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1d090 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1d0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1d0b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1d0c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d0d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1d0e0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1d0f0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
1d100 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1d110 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1d120 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1d130 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1d140 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66  6 string.  The f
1d150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1d160 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
1d170 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
1d180 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
1d190 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
1d1a0 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64  ment. The second
1d1b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d1c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
1d1d0 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  er.  The leftmos
1d1e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
1d1f0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1d200 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1d210 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1d220 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1d230 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1d240 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
1d250 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
1d260 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
1d270 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
1d280 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
1d290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1d2a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
1d2b0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
1d2c0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
1d2d0 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
1d2e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1d2f0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1d300 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1d310 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1d320 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1d330 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1d340 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1d350 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1d360 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1d370 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1d380 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
1d390 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
1d3a0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
1d3b0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
1d3c0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
1d3d0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
1d3e0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
1d3f0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
1d400 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
1d410 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
1d420 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
1d430 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
1d440 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
1d450 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
1d460 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52  he next..**.** R
1d470 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1d480 5b 48 31 33 37 32 31 5d 20 5b 48 31 33 37 32 33  [H13721] [H13723
1d490 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 33 37  ] [H13724] [H137
1d4a0 32 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48 31  25] [H13726] [H1
1d4b0 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63  3727].*/.const c
1d4c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1d4d0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
1d4e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
1d4f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1d500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1d510 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1d520 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
1d530 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
1d540 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
1d550 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
1d560 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  40} <S10700>.**.
1d570 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d580 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
1d590 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
1d5a0 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
1d5b0 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
1d5c0 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
1d5d0 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c  result of a [SEL
1d5e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
1d5f0 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
1d600 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1d610 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
1d620 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
1d630 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
1d640 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
1d650 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
1d660 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
1d670 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d680 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1d690 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
1d6a0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
1d6b0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
1d6c0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
1d6d0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
1d6e0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
1d6f0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
1d700 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1d710 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1d720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d730 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
1d740 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
1d750 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1d760 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
1d770 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
1d780 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
1d790 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
1d7a0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
1d7b0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
1d7c0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
1d7d0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
1d7e0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
1d7f0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
1d800 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
1d810 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1d820 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1d830 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
1d840 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
1d850 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
1d860 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
1d870 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1d880 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
1d890 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1d8a0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
1d8b0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
1d8c0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
1d8d0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
1d8e0 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  ** If the Nth co
1d8f0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
1d900 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1d910 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
1d920 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
1d930 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
1d940 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
1d950 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
1d960 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
1d970 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75  NULL.  These rou
1d980 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1d990 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1d9a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d9b0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
1d9c0 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  rs.  Otherwise, 
1d9d0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
1d9e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
1d9f0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
1da00 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75  able.** and colu
1da10 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
1da20 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
1da30 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
1da40 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
1da50 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
1da60 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
1da70 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
1da80 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
1da90 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
1daa0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
1dab0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
1dac0 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  8. {END}.**.** T
1dad0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
1dae0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1daf0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1db00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1db10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
1db20 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1db30 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
1db40 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
1db50 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  ed..**.** {A1375
1db60 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  1}.** If two or 
1db70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
1db80 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
1db90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1dba0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
1dbb0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
1dbc0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
1dbd0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
1dbe0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
1dbf0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
1dc00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ined..**.** Requ
1dc10 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1dc20 33 37 34 31 5d 20 5b 48 31 33 37 34 32 5d 20 5b  3741] [H13742] [
1dc30 48 31 33 37 34 33 5d 20 5b 48 31 33 37 34 34 5d  H13743] [H13744]
1dc40 20 5b 48 31 33 37 34 35 5d 20 5b 48 31 33 37 34   [H13745] [H1374
1dc50 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a  6] [H13748].**.*
1dc60 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1dc70 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1dc80 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
1dc90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1dca0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
1dcb0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
1dcc0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
1dcd0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
1dce0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
1dcf0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
1dd00 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
1dd10 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1dd20 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1dd30 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
1dd40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1dd50 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
1dd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1dd70 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1dd80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1dd90 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
1dda0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1ddb0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1ddc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1ddd0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
1dde0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1ddf0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1de00 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
1de10 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1de20 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
1de30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1de40 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
1de50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1de60 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1de70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1de80 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
1de90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1dea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1deb0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
1dec0 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
1ded0 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c  esult {H13760} <
1dee0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
1def0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1df00 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
1df10 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1df20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
1df30 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
1df40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
1df50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1df60 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
1df70 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
1df80 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
1df90 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1dfa0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1dfb0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1dfc0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1dfd0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1dfe0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1dff0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1e000 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1e010 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1e020 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1e030 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1e040 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1e050 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1e060 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1e070 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1e080 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1e090 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
1e0a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
1e0b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
1e0c0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
1e0d0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
1e0e0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
1e0f0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
1e100 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
1e110 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
1e120 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
1e130 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
1e140 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
1e150 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
1e160 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
1e170 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
1e180 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
1e190 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
1e1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1e1b0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
1e1c0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
1e1d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1e1e0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
1e1f0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
1e200 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
1e210 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
1e220 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
1e230 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
1e240 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
1e250 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
1e260 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
1e270 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
1e280 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
1e290 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
1e2a0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
1e2b0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
1e2c0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
1e2d0 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
1e2e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1e2f0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
1e300 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
1e310 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
1e320 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
1e330 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52   values..**.** R
1e340 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1e350 5b 48 31 33 37 36 31 5d 20 5b 48 31 33 37 36 32  [H13761] [H13762
1e360 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f  ] [H13763].*/.co
1e370 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1e380 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
1e390 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1e3a0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1e3b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e3c0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
1e3d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e3e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e3f0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
1e400 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32   Statement {H132
1e410 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a  00} <S10000>.**.
1e420 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
1e430 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e440 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
1e450 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
1e460 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e470 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1e480 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e490 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
1e4a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
1e4b0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
1e4c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
1e4d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e4e0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
1e4f0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
1e500 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
1e510 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
1e520 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
1e530 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
1e540 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
1e550 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
1e560 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
1e570 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
1e580 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
1e590 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
1e5a0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
1e5b0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
1e5c0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
1e5d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1e5e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1e5f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
1e600 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
1e610 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
1e620 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e630 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1e640 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
1e650 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
1e660 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
1e670 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e680 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
1e690 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
1e6a0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1e6b0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
1e6c0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
1e6d0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  **.** In the leg
1e6e0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
1e6f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1e700 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
1e710 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
1e720 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
1e730 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
1e740 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
1e750 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1e760 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
1e770 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
1e780 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
1e790 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
1e7a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1e7b0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
1e7c0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
1e7d0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
1e7e0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
1e7f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
1e800 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
1e810 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
1e820 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1e830 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
1e840 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
1e850 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1e860 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
1e870 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
1e880 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
1e890 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1e8a0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
1e8b0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
1e8c0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
1e8d0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
1e8e0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
1e8f0 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
1e900 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1e910 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
1e920 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
1e930 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
1e940 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
1e950 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
1e960 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
1e970 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1e980 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
1e990 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
1e9a0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
1e9b0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
1e9c0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
1e9d0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
1e9e0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
1e9f0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
1ea00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1ea10 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
1ea20 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
1ea30 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
1ea40 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
1ea50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
1ea60 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
1ea70 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
1ea80 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
1ea90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
1eaa0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
1eab0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
1eac0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
1ead0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
1eae0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
1eaf0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
1eb00 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
1eb10 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
1eb20 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
1eb30 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
1eb40 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
1eb50 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
1eb60 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
1eb70 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53  f data..**.** [S
1eb80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
1eb90 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
1eba0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
1ebb0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
1ebc0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
1ebd0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
1ebe0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
1ebf0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
1ec00 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
1ec10 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
1ec20 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
1ec30 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
1ec40 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1ec50 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67  .** With the leg
1ec60 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
1ec70 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
1ec80 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
1ec90 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
1eca0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
1ecb0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
1ecc0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
1ecd0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
1ece0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
1ecf0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
1ed00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1ed10 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
1ed20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1ed30 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
1ed40 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
1ed50 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
1ed60 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
1ed70 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
1ed80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
1ed90 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
1eda0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
1edb0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
1edc0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
1edd0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
1ede0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
1edf0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
1ee00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1ee10 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
1ee20 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
1ee30 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1ee40 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
1ee50 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
1ee60 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1ee70 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
1ee80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
1ee90 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
1eea0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
1eeb0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
1eec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eed0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
1eee0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
1eef0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
1ef00 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
1ef10 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
1ef20 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
1ef30 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
1ef40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1ef50 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
1ef60 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
1ef70 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
1ef80 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
1ef90 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
1efa0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
1efb0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
1efc0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
1efd0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
1efe0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
1eff0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
1f000 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
1f010 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1f020 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
1f030 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
1f040 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
1f050 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
1f060 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
1f070 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
1f080 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
1f090 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
1f0a0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
1f0b0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
1f0c0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
1f0d0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
1f0e0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
1f0f0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
1f100 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
1f110 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1f120 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1f130 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f140 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
1f150 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
1f160 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1f170 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
1f180 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1f190 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
1f1a0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
1f1b0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
1f1c0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
1f1d0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
1f1e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
1f1f0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
1f200 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
1f210 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
1f220 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1f230 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b  s:.** [H13202] [
1f240 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 36 5d  H15304] [H15306]
1f250 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 33 31   [H15308] [H1531
1f260 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  0].*/.int sqlite
1f270 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
1f280 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1f290 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
1f2a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
1f2b0 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
1f2c0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
1f2d0 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
1f2e0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
1f2f0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
1f300 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
1f310 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  set..**.** Requi
1f320 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1f330 37 37 31 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f  771] [H13772].*/
1f340 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
1f350 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
1f360 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1f370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1f380 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
1f390 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53  ypes {H10265} <S
1f3a0 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a  10110><S10120>.*
1f3b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
1f3c0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48  TE_TEXT.**.** {H
1f3d0 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c  10266} Every val
1f3e0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
1f3f0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
1f400 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
1f410 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
1f420 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
1f430 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
1f440 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
1f450 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1f460 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
1f470 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
1f480 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
1f490 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
1f4a0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1f4b0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
1f4c0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
1f4d0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
1f4e0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
1f4f0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
1f500 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
1f510 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1f520 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
1f530 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
1f540 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
1f550 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
1f560 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
1f570 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
1f580 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
1f590 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
1f5a0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
1f5b0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
1f5c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1f5d0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
1f5e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
1f5f0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
1f600 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
1f610 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1f620 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
1f630 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
1f640 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
1f650 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
1f660 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
1f670 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
1f680 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
1f690 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
1f6a0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
1f6b0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
1f6c0 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30  ry {H13800} <S10
1f6d0 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
1f6e0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
1f6f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
1f700 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1f710 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
1f720 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74  t set query" int
1f730 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
1f740 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1f750 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
1f760 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
1f770 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
1f780 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
1f790 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
1f7a0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
1f7b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1f7c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
1f7d0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
1f7e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1f7f0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
1f800 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
1f810 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
1f820 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
1f830 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
1f840 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
1f850 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
1f860 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
1f870 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1f880 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1f890 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
1f8a0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
1f8b0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
1f8c0 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d  rned.  The leftm
1f8d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
1f8e0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
1f8f0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
1f900 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
1f910 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1f920 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
1f930 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
1f940 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
1f950 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
1f960 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
1f970 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
1f980 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
1f990 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
1f9a0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
1f9b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1f9c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
1f9d0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
1f9e0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
1f9f0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
1fa00 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
1fa10 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
1fa20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1fa30 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
1fa40 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
1fa50 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
1fa60 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
1fa70 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
1fa80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
1fa90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
1faa0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
1fab0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
1fac0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
1fad0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
1fae0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1faf0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
1fb00 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1fb10 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
1fb20 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
1fb30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
1fb40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1fb50 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
1fb60 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
1fb70 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
1fb80 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
1fb90 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
1fba0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
1fbb0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1fbc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
1fbd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1fbe0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
1fbf0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
1fc00 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
1fc10 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
1fc20 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
1fc30 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
1fc40 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
1fc50 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
1fc60 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
1fc70 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
1fc80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
1fc90 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
1fca0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
1fcb0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
1fcc0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
1fcd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
1fce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
1fcf0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
1fd00 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
1fd10 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
1fd20 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
1fd30 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
1fd40 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
1fd50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
1fd60 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1fd70 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1fd80 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
1fd90 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
1fda0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
1fdb0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
1fdc0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
1fdd0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
1fde0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
1fdf0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
1fe00 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
1fe10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
1fe20 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
1fe30 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
1fe40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1fe50 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
1fe60 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1fe70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1fe80 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
1fe90 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
1fea0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
1feb0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
1fec0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1fed0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
1fee0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
1fef0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
1ff00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1ff10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
1ff20 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
1ff30 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
1ff40 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
1ff50 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
1ff60 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
1ff70 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
1ff80 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
1ff90 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
1ffa0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
1ffb0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1ffc0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
1ffd0 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
1ffe0 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
1fff0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
20000 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
20010 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
20020 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
20030 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
20040 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
20050 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
20060 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
20070 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
20080 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
20090 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
200a0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
200b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
200c0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
200d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
200e0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
200f0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
20100 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
20110 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
20120 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
20130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20140 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
20150 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
20160 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
20170 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
20180 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
20190 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
201a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
201b0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
201c0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
201d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
201e0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
201f0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
20200 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
20210 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
20220 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
20230 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
20240 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
20250 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
20260 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
20270 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
20280 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
20290 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
202a0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
202b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
202c0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
202d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
202e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
202f0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
20300 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
20310 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
20320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
20330 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
20340 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
20350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20360 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
20370 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
20380 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
20390 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
203a0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
203b0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
203c0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
203d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
203e0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
203f0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
20400 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
20410 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
20420 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
20430 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
20440 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20450 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
20460 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
20470 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
20480 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
20490 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
204a0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
204b0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
204c0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
204d0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
204e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
204f0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
20500 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
20510 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
20520 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
20530 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
20540 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
20550 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
20560 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
20570 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
20580 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
20590 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
205a0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
205b0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
205c0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
205d0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
205e0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
205f0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
20600 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
20610 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
20620 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
20630 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
20640 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
20650 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
20660 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
20670 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
20680 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
20690 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
206a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
206b0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
206c0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
206d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
206e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
206f0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
20700 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
20710 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
20720 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
20730 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
20740 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
20750 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
20760 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
20770 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
20780 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
20790 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
207a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
207b0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
207c0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
207d0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
207e0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
207f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
20800 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
20810 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
20820 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
20830 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
20840 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
20850 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
20860 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
20870 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
20880 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
20890 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
208a0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
208b0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
208c0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
208d0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
208e0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
208f0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
20900 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
20910 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
20920 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
20930 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
20940 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
20950 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
20960 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
20970 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
20980 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
20990 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
209a0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
209b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
209c0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
209d0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
209e0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
209f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
20a00 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
20a10 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
20a20 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
20a30 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
20a40 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
20a50 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
20a60 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
20a70 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
20a80 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
20a90 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
20aa0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
20ab0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
20ac0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
20ad0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
20ae0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
20af0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
20b00 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
20b10 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
20b20 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
20b30 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
20b40 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
20b50 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
20b60 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
20b70 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
20b80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
20b90 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
20ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
20bb0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
20bc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
20bd0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
20be0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
20bf0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
20c00 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
20c10 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
20c20 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
20c30 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
20c40 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
20c50 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
20c60 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
20c70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
20c80 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
20c90 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
20ca0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
20cb0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
20cc0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
20cd0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
20ce0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
20cf0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
20d00 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
20d10 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
20d20 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
20d30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
20d40 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
20d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20d60 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
20d70 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
20d80 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
20d90 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
20da0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
20db0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
20dc0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
20dd0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
20de0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
20df0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
20e00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
20e10 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
20e20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
20e30 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
20e40 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
20e50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
20e60 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
20e70 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
20e80 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
20e90 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
20ea0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
20eb0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
20ec0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
20ed0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
20ee0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
20ef0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
20f00 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
20f10 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
20f20 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
20f30 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
20f40 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
20f50 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
20f60 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
20f70 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
20f80 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
20f90 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
20fa0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
20fb0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
20fc0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
20fd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
20fe0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
20ff0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
21000 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
21010 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
21020 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
21030 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
21040 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
21050 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
21060 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
21070 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
21080 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
21090 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
210a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
210b0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
210c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
210d0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
210e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
210f0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
21100 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
21110 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
21120 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
21130 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
21140 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
21150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21160 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
21170 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21180 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
21190 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
211a0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
211b0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
211c0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
211d0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
211e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
211f0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
21200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21210 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
21220 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
21230 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
21240 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
21250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21260 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
21270 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
21280 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
21290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
212a0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
212b0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
212c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
212d0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
212e0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
212f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
21300 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21310 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
21320 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
21330 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
21340 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
21350 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
21360 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
21370 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
21380 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
21390 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
213a0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
213b0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
213c0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
213d0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
213e0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
213f0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
21400 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
21410 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
21420 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
21430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21440 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
21450 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
21460 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
21470 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
21480 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
21490 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
214a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
214b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
214c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
214d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
214e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
214f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
21500 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
21510 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
21520 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
21530 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
21540 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
21550 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
21560 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
21570 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
21580 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
21590 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
215a0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
215b0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d  nts:.** [H13803]
215c0 20 5b 48 31 33 38 30 36 5d 20 5b 48 31 33 38 30   [H13806] [H1380
215d0 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b 48 31 33  9] [H13812] [H13
215e0 38 31 35 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48  815] [H13818] [H
215f0 31 33 38 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a  13821] [H13824].
21600 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b 48 31 33  ** [H13827] [H13
21610 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  830].*/.const vo
21620 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21630 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
21640 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
21650 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
21660 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
21670 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
21680 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
21690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
216a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
216b0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
216c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
216d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
216e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
216f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
21700 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
21710 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
21720 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
21730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
21740 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
21750 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
21760 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
21770 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
21780 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
21790 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
217a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
217b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
217c0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
217d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
217e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
217f0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
21800 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
21810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
21820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
21830 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
21840 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
21850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
21860 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
21870 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
21880 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30  ct {H13300} <S70
21890 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  300><S30100>.**.
218a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
218b0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
218c0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
218d0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
218e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
218f0 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
21900 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20  nt was executed 
21910 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20  successfully or 
21920 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
21930 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  all, then.** SQL
21940 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
21950 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e  ed. If execution
21960 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
21970 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
21980 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
21990 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
219a0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
219b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
219c0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
219d0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
219e0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
219f0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
21a00 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
21a10 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
21a20 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
21a30 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
21a40 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
21a50 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
21a60 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
21a70 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
21a80 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
21a90 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
21aa0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
21ab0 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e  nterrupt]..** In
21ac0 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
21ad0 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
21ae0 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
21af0 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
21b00 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
21b10 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
21b20 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
21b30 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
21b40 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
21b50 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
21b60 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
21b70 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 31 33  * [H11302] [H113
21b80 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  04].*/.int sqlit
21b90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
21ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
21bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21bc0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
21bd0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
21be0 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
21bf0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
21c00 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
21c10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
21c20 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
21c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21c40 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
21c50 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
21c60 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
21c70 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
21c80 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
21c90 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
21ca0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
21cb0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
21cc0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
21cd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
21ce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
21cf0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
21d00 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
21d10 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
21d20 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
21d30 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
21d40 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
21d50 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
21d60 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
21d70 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
21d80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21d90 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
21da0 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
21db0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
21dc0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
21dd0 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
21de0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
21df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
21e00 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
21e10 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
21e20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
21e30 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21e40 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
21e50 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
21e60 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
21e70 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
21e80 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
21e90 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
21ea0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
21eb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
21ec0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
21ed0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
21ee0 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
21ef0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
21f00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
21f10 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
21f20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
21f30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
21f40 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
21f50 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
21f60 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
21f70 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
21f80 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
21f90 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
21fa0 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
21fb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
21fc0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
21fd0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
21fe0 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
21ff0 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
22000 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
22010 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
22020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22030 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
22040 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
22050 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
22060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22070 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
22080 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
22090 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
220a0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
220b0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
220c0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
220d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
220e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
220f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
22100 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
22110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
22130 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
22140 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
22150 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
22160 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
22170 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
22180 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
22190 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
221a0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
221b0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
221c0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
221d0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
221e0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
221f0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
22200 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
22210 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
22220 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
22230 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
22240 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
22250 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
22260 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
22270 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
22280 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
22290 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
222a0 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
222b0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
222c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
222d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
222e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
222f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22300 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
22310 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
22320 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
22330 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
22340 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
22350 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
22360 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
22370 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
22380 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
22390 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
223a0 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
223b0 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
223c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
223d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
223e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
223f0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
22400 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
22410 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
22420 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
22430 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
22440 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
22450 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
22460 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
22470 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
22480 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
22490 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
224a0 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
224b0 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
224c0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
224d0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
224e0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
224f0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
22500 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
22510 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
22520 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
22530 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
22540 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
22550 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
22560 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
22570 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
22580 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
22590 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
225a0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
225b0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
225c0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
225d0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
225e0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
225f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
22600 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22610 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
22620 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
22630 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
22640 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
22650 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
22660 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
22670 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
22680 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
22690 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
226a0 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
226b0 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
226c0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
226d0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
226e0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
226f0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
22700 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
22710 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
22720 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
22730 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
22740 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
22750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
22760 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
22770 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
22780 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
22790 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
227a0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
227b0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
227c0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
227d0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
227e0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
227f0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
22800 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
22810 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
22820 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
22830 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
22840 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
22850 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
22860 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
22870 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
22880 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
22890 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
228a0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
228b0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
228c0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
228d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
228e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
228f0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
22900 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
22910 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
22920 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
22930 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
22940 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
22950 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
22960 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
22970 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
22980 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
22990 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
229a0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
229b0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
229c0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
229d0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
229e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
229f0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
22a00 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
22a10 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
22a20 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
22a30 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
22a40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
22a50 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
22a60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
22a70 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
22a80 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
22a90 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
22aa0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
22ab0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
22ac0 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
22ad0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
22ae0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
22af0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
22b00 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
22b10 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
22b20 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
22b30 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
22b40 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
22b50 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
22b60 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
22b70 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
22b80 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
22b90 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
22ba0 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
22bb0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
22bc0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
22bd0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
22be0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
22bf0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
22c00 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
22c10 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
22c20 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
22c30 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
22c40 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
22c50 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
22c60 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
22c70 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
22c80 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
22c90 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
22ca0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
22cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
22cc0 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69   used.  A functi
22cd0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
22ce0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
22cf0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
22d00 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
22d10 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
22d20 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
22d30 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
22d40 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
22d50 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  .  A function wh
22d60 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
22d70 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
22d80 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
22d90 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
22da0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
22db0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
22dc0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
22dd0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
22de0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75  erent.  .** A fu
22df0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
22e00 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
22e10 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
22e20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
22e30 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
22e40 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
22e50 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
22e60 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
22e70 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
22e80 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
22e90 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74  F16..**.** Built
22ea0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
22eb0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
22ec0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
22ed0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
22ee0 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ions..** The fir
22ef0 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  st application-d
22f00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
22f10 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d  with a given nam
22f20 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a  e overrides all.
22f30 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** built-in func
22f40 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d  tions in the sam
22f50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
22f60 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65  ection] with the
22f70 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53   same name..** S
22f80 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
22f90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
22fa0 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
22fb0 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
22fc0 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
22fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
22fe0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
22ff0 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
23000 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
23010 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
23020 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
23030 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
23040 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74  *.** An applicat
23050 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23060 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23070 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
23080 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
23090 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
230a0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
230b0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
230c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
230d0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
230e0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
230f0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
23100 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
23110 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
23120 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  nning..**.** Req
23130 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
23140 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d 20  16103] [H16106] 
23150 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31 32  [H16109] [H16112
23160 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 31  ] [H16118] [H161
23170 32 31 5d 20 5b 48 31 36 31 32 34 5d 20 5b 48 31  21] [H16124] [H1
23180 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 30  6127].** [H16130
23190 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 31  ] [H16133] [H161
231a0 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 31  36] [H16139] [H1
231b0 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6142].*/.int sql
231c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
231d0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
231e0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
231f0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
23200 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
23210 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
23220 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
23230 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
23240 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
23250 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
23260 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
23270 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
23280 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
23290 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
232a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
232b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
232c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
232d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
232e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
232f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
23300 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
23310 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
23320 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
23330 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
23340 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
23350 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
23360 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
23370 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
23380 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
23390 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
233a0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
233b0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
233c0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
233d0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
233e0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37  ncodings {H10267
233f0 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31  } <S50200> <H161
23400 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
23410 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
23420 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
23430 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
23440 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
23450 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
23460 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
23470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23480 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
23490 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
234a0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
234b0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
234c0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
234d0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
234e0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
234f0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
23500 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
23510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23520 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
23530 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
23540 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
23550 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
23560 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
23570 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
23580 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
23590 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
235a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
235b0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
235c0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
235d0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
235e0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
235f0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
23600 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
23610 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
23620 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
23630 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
23640 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
23650 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
23660 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
23670 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
23680 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
23690 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
236a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
236b0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
236c0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
236d0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
236e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
236f0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
23700 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
23710 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
23720 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
23730 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
23740 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
23750 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
23760 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
23770 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
23780 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
23790 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
237a0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
237b0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
237c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
237d0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
237e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
237f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
23800 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
23810 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
23820 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
23830 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
23840 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
23850 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
23860 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
23870 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
23880 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
23890 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
238a0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
238b0 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
238c0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
238d0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
238e0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
238f0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
23900 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
23910 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
23920 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
23930 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
23940 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
23950 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
23960 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
23970 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
23980 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
23990 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
239a0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
239b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
239c0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
239d0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
239e0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
239f0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
23a00 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
23a10 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
23a20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23a30 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
23a40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23a50 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
23a60 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
23a70 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
23a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
23a90 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
23aa0 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
23ab0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
23ac0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
23ad0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
23ae0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
23af0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23b00 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
23b10 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
23b20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
23b30 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
23b40 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
23b50 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
23b60 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
23b70 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
23b80 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
23b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23ba0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
23bb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
23bc0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
23bd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23be0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
23bf0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
23c00 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
23c10 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
23c20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23c30 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
23c40 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
23c50 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
23c60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
23c70 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
23c80 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
23c90 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
23ca0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
23cb0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
23cc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
23cd0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
23ce0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23cf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
23d00 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
23d10 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
23d20 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
23d30 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
23d40 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
23d50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
23d60 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
23d70 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
23d80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
23d90 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
23da0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
23db0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
23dc0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
23dd0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
23de0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
23df0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
23e00 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
23e10 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
23e20 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
23e30 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
23e40 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
23e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23e60 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
23e70 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
23e80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
23e90 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
23ea0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
23eb0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
23ec0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
23ed0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
23ee0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
23ef0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
23f00 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
23f10 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
23f20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
23f30 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
23f40 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
23f50 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
23f60 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
23f70 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
23f80 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
23f90 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
23fa0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
23fb0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
23fc0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
23fd0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
23fe0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
23ff0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
24000 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
24010 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
24020 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
24030 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
24040 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
24050 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
24060 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
24070 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
24080 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
24090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
240a0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
240b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
240c0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
240d0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
240e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
240f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
24100 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
24110 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
24120 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
24130 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
24140 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
24150 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
24160 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24170 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
24180 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
24190 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
241a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
241b0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
241c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
241d0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
241e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
241f0 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b 48  :.** [H15103] [H
24200 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d 20  15106] [H15109] 
24210 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31 35  [H15112] [H15115
24220 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35 31  ] [H15118] [H151
24230 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a 20  21] [H15124].** 
24240 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33 30  [H15127] [H15130
24250 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35 31  ] [H15133] [H151
24260 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  36].*/.const voi
24270 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
24280 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
24290 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
242a0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
242b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
242c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
242d0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
242e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
242f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
24300 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
24310 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
24320 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
24330 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
24340 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
24350 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
24360 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24370 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
24380 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
24390 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
243a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
243b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
243c0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
243d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
243e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
243f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
24400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24410 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24420 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24430 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
24440 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24450 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
24460 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
24470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
24480 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
24490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
244a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
244b0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
244c0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
244d0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
244e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
244f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
24500 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
24510 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
24520 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
24530 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
24540 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
24550 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
24560 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
24570 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
24580 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
24590 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
245a0 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
245b0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
245c0 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
245d0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
245e0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
245f0 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
24600 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
24610 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
24620 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
24630 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
24640 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
24650 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
24660 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
24670 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
24680 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
24690 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
246a0 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
246b0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
246c0 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
246d0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
246e0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
246f0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
24700 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
24710 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
24720 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
24730 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
24740 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
24750 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
24760 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
24770 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
24780 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
24790 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
247a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
247b0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
247c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
247d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
247e0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
247f0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
24800 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
24810 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
24820 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
24830 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
24840 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
24850 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
24860 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
24870 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
24880 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
24890 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b  s:.** [H16211] [
248a0 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35 5d  H16213] [H16215]
248b0 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69   [H16217].*/.voi
248c0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
248d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
248e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
248f0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
24900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
24910 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
24920 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53  ions {H16240} <S
24930 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
24940 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
24950 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
24960 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
24970 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
24980 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
24990 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
249a0 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
249b0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
249c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
249d0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
249e0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
249f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
24a00 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
24a10 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
24a20 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
24a30 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
24a40 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
24a50 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
24a60 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
24a70 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
24a80 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
24a90 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
24aa0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
24ab0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
24ac0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
24ad0 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a 2a  s:.** [H16243].*
24ae0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
24af0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
24b00 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
24b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
24b20 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
24b30 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
24b40 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30  {H16250} <S60600
24b50 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20200>.**.** 
24b60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
24b70 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
24b80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24b90 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
24ba0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
24bb0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24bc0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
24bd0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
24be0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
24bf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
24c00 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
24c10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24c20 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
24c30 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
24c40 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
24c50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
24c60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
24c70 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
24c80 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d 0a  ts:.** [H16253].
24c90 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
24ca0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
24cb0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
24cc0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
24cd0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
24ce0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
24cf0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
24d00 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
24d10 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
24d20 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
24d30 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
24d40 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
24d50 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
24d60 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
24d70 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
24d80 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
24d90 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
24da0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
24db0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
24dc0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
24dd0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
24de0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
24df0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
24e00 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
24e10 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
24e20 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
24e30 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
24e40 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
24e50 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
24e60 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
24e70 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
24e80 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
24e90 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
24ea0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
24eb0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
24ec0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
24ed0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
24ee0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
24ef0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
24f00 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
24f10 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
24f20 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
24f30 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
24f40 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
24f50 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
24f60 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
24f70 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
24f80 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
24f90 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
24fa0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
24fb0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
24fc0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
24fd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24fe0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
24ff0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25000 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
25010 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
25020 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
25030 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
25040 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
25050 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
25060 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
25070 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
25080 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25090 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
250a0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
250b0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
250c0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
250d0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
250e0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
250f0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
25100 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
25110 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
25120 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
25130 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
25140 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
25150 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
25160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
25170 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25180 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
25190 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
251a0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
251b0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
251c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
251d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
251e0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
251f0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
25200 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25210 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
25220 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
25230 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
25240 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
25250 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
25260 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
25270 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
25280 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
25290 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
252a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
252b0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
252c0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
252d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
252e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
252f0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
25300 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
25310 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
25320 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
25330 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
25340 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
25350 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
25360 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
25370 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
25380 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
25390 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
253a0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
253b0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
253c0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
253d0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
253e0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
253f0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
25400 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
25410 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
25420 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
25430 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
25440 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
25450 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
25460 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
25470 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
25480 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
25490 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
254a0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
254b0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
254c0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
254d0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
254e0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
254f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
25500 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
25510 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
25520 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
25530 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
25540 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
25550 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
25560 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
25570 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b  6272] [H16274] [
25580 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d  H16276] [H16277]
25590 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37   [H16278] [H1627
255a0 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  9].*/.void *sqli
255b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
255c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
255d0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
255e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
255f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
25600 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
25610 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
25620 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
25630 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
25640 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
25650 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
25660 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c  avior {H10280} <
25670 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
25680 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
25690 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
256a0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
256b0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
256c0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
256d0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
256e0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
256f0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
25700 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
25710 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
25720 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
25730 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
25740 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
25750 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
25760 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
25770 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
25780 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
25790 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a  destroyed.  The.
257a0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
257b0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
257c0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
257d0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
257e0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
257f0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
25800 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
25810 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
25820 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
25830 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
25840 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
25850 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
25860 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
25870 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
25880 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
25890 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
258a0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
258b0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
258c0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
258d0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
258e0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
258f0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
25900 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
25910 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
25920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25930 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
25940 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
25950 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
25960 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
25970 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
25980 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
25990 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30   {H16400} <S2020
259a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
259b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
259c0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
259d0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
259e0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
259f0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
25a00 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
25a10 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
25a20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25a30 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
25a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25a50 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
25a60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
25a70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
25a80 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
25a90 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
25aa0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
25ab0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
25ac0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
25ad0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
25ae0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
25af0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
25b00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
25b10 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
25b20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
25b30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
25b40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
25b50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
25b60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
25b70 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
25b80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
25b90 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
25ba0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25bb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
25bc0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
25bd0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
25be0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
25bf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25c00 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
25c10 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
25c20 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
25c30 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
25c40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25c50 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
25c60 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
25c70 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
25c80 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
25c90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
25ca0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
25cb0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
25cc0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
25cd0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
25ce0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
25cf0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
25d00 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
25d10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
25d20 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
25d30 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
25d40 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
25d50 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
25d60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
25d70 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
25d80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
25d90 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
25da0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
25db0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25dc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
25dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
25de0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
25df0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
25e00 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
25e10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
25e20 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
25e30 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
25e40 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
25e50 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
25e60 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
25e70 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
25e80 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
25e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
25ea0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
25eb0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
25ec0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
25ed0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
25ee0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
25ef0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
25f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
25f10 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
25f20 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
25f30 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
25f40 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
25f50 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
25f60 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
25f70 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
25f80 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20  .  If the third 
25f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
25fb0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
25fc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
25fd0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
25fe0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
25ff0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
26000 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
26010 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
26020 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
26030 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
26040 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
26050 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
26060 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
26070 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26080 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
26090 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
260a0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
260b0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
260c0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
260d0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
260e0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
260f0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
26100 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
26110 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
26120 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26130 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
26140 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
26150 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
26160 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
26170 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
26180 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
26190 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
261a0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
261b0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
261c0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
261d0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
261e0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
261f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26200 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
26210 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
26220 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
26230 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
26240 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
26250 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
26260 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
26270 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
26280 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
26290 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
262a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
262b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
262c0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
262d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
262e0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
262f0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
26300 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
26310 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26320 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
26330 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
26340 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
26350 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
26360 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
26370 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
26380 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72   to long to repr
26390 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  esent..**.** The
263a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
263b0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
263c0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
263d0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
263e0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
263f0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
26400 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
26410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26420 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
26430 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
26440 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
26450 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
26460 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26470 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
26480 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
26490 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
264a0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
264b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
264c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
264d0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
264e0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
264f0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
26500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26510 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26520 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
26530 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
26540 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
26550 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
26560 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
26570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
26580 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
26590 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
265a0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
265b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
265c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
265d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
265e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
265f0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
26600 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
26610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
26620 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
26630 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
26640 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
26650 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
26660 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
26670 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
26680 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26690 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
266a0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
266b0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
266c0 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
266d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
266e0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
266f0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
26700 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
26710 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
26720 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
26730 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
26740 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
26750 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
26760 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
26770 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
26780 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
26790 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
267a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
267b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
267c0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
267d0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
267e0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
267f0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
26800 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
26810 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
26820 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
26830 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
26840 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
26850 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
26870 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
26880 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
26890 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
268a0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
268b0 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
268c0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
268d0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
268e0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
268f0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
26900 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
26910 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
26920 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
26930 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26940 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26950 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
26960 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
26970 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
26980 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
26990 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
269a0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
269b0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
269c0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
269d0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
269e0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
269f0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
26a00 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
26a10 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
26a20 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
26a30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
26a40 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20  nterfaces or.** 
26a50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
26a60 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
26a70 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
26a80 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
26a90 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
26aa0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
26ab0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
26ac0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
26ad0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
26ae0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20  .** copy the it 
26af0 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
26b00 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73  ctor when it has
26b10 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
26b20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
26b30 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
26b40 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
26b50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26b60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
26b70 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
26b80 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
26b90 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
26ba0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
26bb0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
26bc0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
26bd0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
26be0 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
26bf0 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
26c00 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
26c10 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
26c20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26c30 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
26c40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26c50 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
26c60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26c70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26c80 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
26c90 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
26ca0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26cb0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
26cc0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
26cd0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a  rameter.  The.**
26ce0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26cf0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
26d00 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
26d10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
26d20 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
26d30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
26d40 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
26d50 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
26d60 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
26d70 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
26d80 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
26d90 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
26da0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
26db0 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74  m..** A [protect
26dc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26dd0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
26de0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
26df0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
26e00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26e10 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
26e20 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
26e30 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
26e40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
26e50 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
26e60 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
26e70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
26e80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26e90 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
26ea0 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
26eb0 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
26ec0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
26ed0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
26ee0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26ef0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
26f00 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
26f10 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
26f20 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
26f30 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
26f40 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26f50 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d 20  ts:.** [H16403] 
26f60 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30 39  [H16406] [H16409
26f70 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36 34  ] [H16412] [H164
26f80 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48 31  15] [H16418] [H1
26f90 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a 2a  6421] [H16424].*
26fa0 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36 34  * [H16427] [H164
26fb0 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48 31  30] [H16433] [H1
26fc0 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20 5b  6436] [H16439] [
26fd0 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35 5d  H16442] [H16445]
26fe0 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48 31   [H16448].** [H1
26ff0 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20 5b  6451] [H16454] [
27000 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30 5d  H16457] [H16460]
27010 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69   [H16463].*/.voi
27020 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27030 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
27040 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
27050 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
27060 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
27080 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
27090 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
270a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
270b0 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
270c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
270d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
270e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
270f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
27100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27110 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
27120 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27130 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
27140 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
27150 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
27160 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
27170 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
27180 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
27190 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
271a0 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
271b0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
271c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
271d0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
271e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
271f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
27200 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
27210 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
27220 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
27230 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
27240 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
27250 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
27260 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
27270 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27280 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
27290 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
272a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
272b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
272c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
272d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
272e0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
272f0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
27300 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
27310 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
27320 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
27330 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
27340 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27350 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27360 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
27370 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
27380 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
27390 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
273a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
273b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
273c0 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
273d0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
273e0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
273f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27400 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
27410 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
27420 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
27430 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36   Sequences {H166
27440 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
27450 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
27460 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
27470 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
27480 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
27490 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
274a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
274b0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
274c0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
274d0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
274e0 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
274f0 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
27500 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
27510 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
27520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27530 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
27540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
27550 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
27560 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
27570 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
27580 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
27590 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
275a0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
275b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
275c0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
275d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
275e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
275f0 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
27600 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
27610 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
27620 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
27630 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
27640 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
27650 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
27660 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
27670 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
27680 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
27690 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
276a0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
276b0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
276c0 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
276d0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
276e0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
276f0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
27700 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
27710 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
27720 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
27730 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
27740 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
27750 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
27760 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
27770 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
27780 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
27790 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
277a0 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
277b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
277c0 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
277d0 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
277e0 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
277f0 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
27800 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
27810 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
27820 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
27830 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
27840 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
27850 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
27860 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
27870 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
27880 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
27890 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
278a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
278b0 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
278c0 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
278d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
278e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
278f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
27900 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
27910 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
27920 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
27930 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
27940 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
27950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
27960 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
27970 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
27980 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
27990 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
279a0 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
279b0 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
279c0 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
279d0 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
279e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
279f0 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
27a00 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
27a10 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
27a20 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
27a30 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
27a40 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
27a50 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
27a60 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
27a70 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
27a80 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
27a90 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
27aa0 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
27ab0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
27ac0 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
27ad0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
27ae0 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
27af0 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
27b00 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
27b10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27b20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27b30 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
27b40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27b50 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
27b60 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
27b70 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
27b80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
27b90 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
27ba0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
27bb0 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
27bc0 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
27bd0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
27be0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
27bf0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
27c00 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
27c10 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
27c20 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
27c30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
27c40 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27c50 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
27c60 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
27c70 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
27c80 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
27c90 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
27ca0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
27cb0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
27cc0 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
27cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27ce0 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
27cf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
27d00 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  e()]..**.** Requ
27d10 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
27d20 36 36 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b  6603] [H16604] [
27d30 48 31 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d  H16606] [H16609]
27d40 20 5b 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31   [H16612] [H1661
27d50 35 5d 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36  5] [H16618] [H16
27d60 36 32 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d  621].** [H16624]
27d70 20 5b 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33   [H16627] [H1663
27d80 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  0].*/.int sqlite
27d90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
27da0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
27db0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27dc0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
27dd0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
27de0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
27df0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
27e00 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
27e10 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
27e20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27e30 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
27e40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
27e50 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
27e60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
27e70 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
27e80 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
27e90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
27ea0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
27eb0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
27ec0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
27ed0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
27ee0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
27ef0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
27f00 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
27f10 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
27f20 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
27f30 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
27f40 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
27f50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
27f60 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
27f70 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
27f80 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
27f90 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33  s {H16700} <S203
27fa0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00>.**.** To avo
27fb0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
27fc0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
27fd0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
27fe0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
27ff0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
28000 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
28010 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
28020 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
28030 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
28040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
28050 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  o be called when
28060 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
28070 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
28080 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
28090 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  red..**.** If th
280a0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
280b0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
280c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
280d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
280e0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
280f0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
28100 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
28110 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
28120 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
28130 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
28140 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73  8. {H16703} If s
28150 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
28160 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
28170 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
28180 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
28190 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
281a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
281b0 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  der..** A call t
281c0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
281d0 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
281e0 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
281f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
28200 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
28210 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
28220 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
28230 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
28240 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
28250 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
28260 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
28270 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
28280 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
28290 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
282a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
282b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
282c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
282d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
282e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
282f0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
28300 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
28310 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
28320 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
28330 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
28340 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
28350 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
28360 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
28370 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
28380 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28390 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
283a0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
283b0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
283c0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
283d0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
283e0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
283f0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
28400 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
28410 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28420 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
28430 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
28440 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
28450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28460 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
28470 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
28480 0a 2a 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31  .** [H16702] [H1
28490 36 37 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a  6704] [H16706].*
284a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
284b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
284c0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
284d0 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
284e0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
284f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
28500 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
28510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
28520 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
28530 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
28540 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
28550 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
28560 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
28570 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
28580 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
28590 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
285a0 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
285b0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
285c0 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
285d0 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
285e0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
285f0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
28600 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
28610 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
28620 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
28630 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
28640 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
28650 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
28660 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
28670 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28680 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
28690 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
286a0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
286b0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
286c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
286d0 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
286e0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
286f0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
28700 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
28710 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
28720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
28730 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
28740 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
28750 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
28760 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
28770 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
28780 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
28790 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
287a0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
287b0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
287c0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
287d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
287e0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
287f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
28800 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28810 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
28820 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
28830 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
28840 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
28850 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
28860 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
28870 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
28880 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30   Short Time {H10
28890 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  530} <S40410>.**
288a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
288b0 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
288c0 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
288d0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
288e0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
288f0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
28900 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
28910 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
28920 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
28930 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
28940 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
28950 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
28960 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
28970 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
28980 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
28990 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
289a0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
289b0 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
289c0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
289d0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
289e0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
289f0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
28a00 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
28a10 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
28a20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
28a30 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ed..**.** SQLite
28a40 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
28a50 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
28a60 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
28a70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
28a80 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
28a90 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
28aa0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
28ab0 65 6e 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b  ents: [H10533] [
28ac0 48 31 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73  H10536].*/.int s
28ad0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
28ae0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28af0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
28b00 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
28b10 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
28b20 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e  H10310} <S20000>
28b30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67  .**.** If this g
28b40 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
28b50 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
28b60 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
28b70 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
28b80 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
28b90 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
28ba0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
28bb0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
28bc0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
28bd0 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
28be0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
28bf0 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62    If this variab
28c00 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
28c10 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
28c20 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
28c30 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
28c40 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
28c50 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
28c60 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
28c70 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
28c80 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
28c90 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
28ca0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
28cb0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
28cc0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
28cd0 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
28ce0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
28cf0 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
28d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28d10 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
28d20 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
28d30 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
28d40 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
28d50 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
28d60 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
28d70 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
28d80 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
28d90 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
28da0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
28db0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
28dc0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
28dd0 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
28de0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
28df0 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
28e00 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
28e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d  ..**.** The [tem
28e20 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
28e30 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
28e40 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
28e50 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
28e60 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
28e70 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
28e80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
28e90 6c 6f 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f  loc].  Furthermo
28ea0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
28eb0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
28ec0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
28ed0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
28ee0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
28ef0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
28f00 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
28f10 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
28f20 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
28f30 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
28f40 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
28f50 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
28f60 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
28f70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
28f80 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
28f90 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
28fa0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
28fb0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
28fc0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
28fd0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
28fe0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
28ff0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
29000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
29010 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
29020 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
29030 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
29040 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
29050 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
29060 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
29070 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
29080 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
29090 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
290a0 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
290b0 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c   Mode {H12930} <
290c0 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S60200>.** KEYWO
290d0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
290e0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   mode}.**.** The
290f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
29100 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
29110 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
29120 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
29130 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
29140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29150 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
29160 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
29170 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
29180 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  y.  Autocommit m
29190 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
291a0 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ault..** Autocom
291b0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
291c0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
291d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
291e0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
291f0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
29200 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
29210 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
29220 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
29230 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
29240 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
29250 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
29260 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
29270 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
29280 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
29290 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
292a0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
292b0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
292c0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
292d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
292e0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
292f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
29300 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
29310 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
29320 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
29330 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
29340 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
29350 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
29360 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
29370 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
29380 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
29390 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
293a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
293b0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
293c0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
293d0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
293e0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
293f0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
29400 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
29410 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
29420 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
29430 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29440 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
29450 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d  H12931] [H12932]
29460 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33   [H12933] [H1293
29470 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  4].*/.int sqlite
29480 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
29490 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
294a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
294b0 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
294c0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
294d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
294e0 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a  13120} <S60600>.
294f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29500 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
29510 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
29520 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29530 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
29540 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
29550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29560 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20  ] belongs.  The 
29570 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29580 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  tion].** returne
29590 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
295a0 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
295b0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
295c0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61  nection] that wa
295d0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
295e0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
295f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29600 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
29610 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
29620 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
29630 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
29640 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
29650 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  st place..**.** 
29660 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
29670 31 33 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65  13123].*/.sqlite
29680 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
29690 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
296a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
296b0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
296c0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
296d0 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20  tement {H13140} 
296e0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
296f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
29700 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
29710 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
29720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29730 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
29740 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29750 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
29760 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
29770 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
29780 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
29790 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
297a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
297b0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
297c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
297d0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
297e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
297f0 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f  tion pDb.  If no
29800 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29810 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
29820 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
29830 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
29840 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
29850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
29860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29870 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
29880 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
29890 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
298a0 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
298b0 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
298c0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
298d0 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
298e0 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
298f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
29900 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
29910 74 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31  ts: [H13143] [H1
29920 33 31 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b  3146] [H13149] [
29930 48 31 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74  H13152].*/.sqlit
29940 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
29950 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
29960 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
29970 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
29980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29990 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
299a0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
299b0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
299c0 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  50} <S60400>.**.
299d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
299e0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
299f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
29a00 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
29a10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
29a20 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
29a30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
29a40 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
29a50 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
29a60 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
29a70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
29a80 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
29a90 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
29aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29ab0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
29ac0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c   The sqlite3_rol
29ad0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
29ae0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
29af0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
29b00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
29b10 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
29b20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
29b30 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
29b40 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
29b50 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
29b60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
29b70 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
29b80 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
29b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29ba0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
29bb0 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
29bc0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
29bd0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
29be0 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  back..** If the 
29bf0 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
29c00 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
29c10 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
29c20 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
29c30 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
29c40 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
29c50 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  back..**.** If a
29c60 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
29c70 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
29c80 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a  egistered, its.*
29c90 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  * pArg value is 
29ca0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
29cb0 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
29cc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
29cd0 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
29ce0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
29cf0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
29d00 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
29d10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
29d20 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
29d30 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
29d40 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
29d50 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
29d60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29d70 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
29d80 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
29d90 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
29da0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
29db0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
29dc0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
29dd0 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
29de0 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
29df0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
29e00 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
29e10 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
29e20 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
29e30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
29e40 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
29e50 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
29e60 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
29e70 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
29e80 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
29e90 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  graph..**.** Reg
29ea0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
29eb0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
29ec0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
29ed0 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
29ee0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
29ef0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
29f00 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
29f10 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
29f20 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
29f30 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
29f40 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
29f50 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
29f60 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
29f70 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
29f80 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
29f90 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
29fa0 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
29fb0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
29fc0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
29fd0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
29fe0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
29ff0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2a000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a010 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2a020 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2a030 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2a040 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2a050 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
2a060 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2a070 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
2a080 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
2a090 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
2a0a0 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
2a0b0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  todo>.**.** Requ
2a0c0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
2a0d0 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b  2951] [H12952] [
2a0e0 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d  H12953] [H12954]
2a0f0 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31   [H12955].** [H1
2a100 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b  2961] [H12962] [
2a110 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d  H12963] [H12964]
2a120 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2a130 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2a140 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2a150 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2a160 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2a170 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2a180 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2a190 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2a1a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a1b0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2a1c0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2a1d0 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34  s {H12970} <S604
2a1e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2a1f0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2a200 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2a210 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2a220 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2a230 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2a240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2a250 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2a260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2a270 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2a280 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2a290 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2a2a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2a2b0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2a2c0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2a2d0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2a2e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2a2f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2a300 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2a310 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2a320 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a330 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2a340 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2a350 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2a360 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2a370 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2a380 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68  r deleted..** Th
2a390 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a3a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2a3b0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2a3c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2a3d0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
2a3e0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
2a3f0 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
2a400 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2a410 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2a420 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2a430 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
2a440 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
2a450 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2a460 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2a470 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2a480 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
2a490 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
2a4a0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2a4b0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2a4c0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2a4d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2a4e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2a4f0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2a500 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2a510 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
2a520 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2a530 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a540 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
2a550 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
2a560 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2a570 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2a580 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2a590 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2a5a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2a5b0 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2a5c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2a5d0 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2a5e0 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2a5f0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2a600 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2a610 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a  te_sequence)..**
2a620 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2a630 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
2a640 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
2a650 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
2a660 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
2a670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a680 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
2a690 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2a6a0 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2a6b0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2a6c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a6d0 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2a6e0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2a6f0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2a700 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2a710 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2a720 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2a730 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
2a740 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
2a750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a760 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a770 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
2a780 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
2a790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a7a0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
2a7b0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
2a7c0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
2a7d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
2a7e0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
2a7f0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
2a800 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
2a810 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75  value.** is retu
2a820 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
2a830 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2a840 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
2a850 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37  ments:.** [H1297
2a860 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32  1] [H12973] [H12
2a870 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48  975] [H12977] [H
2a880 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20  12979] [H12981] 
2a890 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36  [H12983] [H12986
2a8a0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
2a8b0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
2a8c0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2a8d0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
2a8e0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
2a8f0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
2a900 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
2a910 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
2a920 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2a930 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
2a940 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48  d Pager Cache {H
2a950 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a  10330} <S30900>.
2a960 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2a970 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61  ared cache} {sha
2a980 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a  red cache mode}.
2a990 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2a9a0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
2a9b0 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
2a9c0 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
2a9d0 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
2a9e0 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
2a9f0 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
2aa00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2aa10 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
2aa20 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
2aa30 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
2aa40 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
2aa50 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2aa60 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
2aa70 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
2aa80 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
2aa90 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61  .**.** Cache sha
2aaa0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2aab0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2aac0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2aad0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2aae0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2aaf0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2ab00 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2ab10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2ab20 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2ab30 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2ab40 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2ab50 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2ab60 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20  **.** The cache 
2ab70 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2ab80 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2ab90 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2aba0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2abb0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2abc0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2abd0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2abe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2abf0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2ac00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ac10 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2ac20 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2ac30 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2ac40 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2ac50 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2ac60 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69  opened..**.** Vi
2ac70 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
2ac80 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68  not be used with
2ac90 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e   a shared cache.
2aca0 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
2acb0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
2acc0 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
2acd0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
2ace0 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
2acf0 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
2ad00 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
2ad10 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
2ad20 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
2ad30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ad40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
2ad50 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
2ad60 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2ad70 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
2ad80 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
2ad90 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2ada0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
2adb0 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
2adc0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
2add0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
2ade0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
2adf0 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
2ae00 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
2ae10 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2ae20 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
2ae30 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
2ae40 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
2ae50 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
2ae60 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
2ae70 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
2ae80 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a  ache Mode].**.**
2ae90 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
2aea0 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36 5d  H10331] [H10336]
2aeb0 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33 33   [H10337] [H1033
2aec0 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
2aed0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2aee0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2aef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
2af00 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
2af10 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30  p Memory {H17340
2af20 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a  } <S30220>.**.**
2af30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
2af40 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
2af50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2af60 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
2af70 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
2af80 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
2af90 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
2afa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2afb0 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
2afc0 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
2afd0 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
2afe0 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ry used to cache
2aff0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
2b000 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
2b010 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
2b020 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65  example of non-e
2b030 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e  ssential memory.
2b040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  .** sqlite3_rele
2b050 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2b060 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2b070 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2b080 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2b090 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2b0a0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2b0b0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2b0c0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
2b0d0 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20  ments: [H17341] 
2b0e0 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20  [H17342].*/.int 
2b0f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2b100 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
2b110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
2b120 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
2b130 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35  Heap Size {H1735
2b140 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a  0} <S30220>.**.*
2b150 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f  * The sqlite3_so
2b160 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
2b170 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
2b180 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a   a "soft" limit.
2b190 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  ** on the amount
2b1a0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2b1b0 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
2b1c0 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
2b1d0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e  .** If an intern
2b1e0 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  al allocation is
2b1f0 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20   requested that 
2b200 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2b210 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69  .** soft heap li
2b220 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
2b230 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
2b240 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  is invoked one o
2b250 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20  r.** more times 
2b260 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
2b270 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
2b280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70   allocation is p
2b290 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
2b2a0 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
2b2b0 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61  led "soft", beca
2b2c0 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  use if [sqlite3_
2b2d0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2b2e0 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65  ].** cannot free
2b2f0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
2b300 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
2b310 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
2b320 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
2b330 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
2b340 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
2b350 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
2b360 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
2b370 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
2b380 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
2b390 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
2b3a0 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
2b3b0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
2b3c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
2b3d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2b3e0 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
2b3f0 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
2b400 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
2b410 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
2b420 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
2b430 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
2b440 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
2b450 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
2b460 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
2b470 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2b480 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  it..** But if th
2b490 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2b4a0 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f  t cannot be hono
2b4b0 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  red, execution w
2b4c0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
2b4d0 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
2b4e0 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20   notification.  
2b4f0 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2b500 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2b510 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2b520 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2b530 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2b540 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2b550 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2b560 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2b570 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2b580 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2b590 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2b5a0 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2b5b0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2b5c0 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2b5d0 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2b5e0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2b5f0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2b600 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2b610 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2b620 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2b630 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2b640 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2b650 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2b660 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2b670 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2b680 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2b690 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2b6a0 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2b6b0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2b6c0 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2b6d0 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2b6e0 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2b6f0 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2b700 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2b710 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31  ents:.** [H16351
2b720 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 33  ] [H16352] [H163
2b730 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 31  53] [H16354] [H1
2b740 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a  6355] [H16358].*
2b750 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2b760 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2b770 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b780 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2b790 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2b7a0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2b7b0 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30   {H12850} <S6030
2b7c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
2b7d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
2b7e0 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
2b7f0 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
2b800 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
2b810 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
2b820 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
2b830 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b840 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2b850 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
2b860 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
2b870 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2b880 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69   The column is i
2b890 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2b8a0 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2b8b0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2b8c0 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2b8d0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
2b8e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2b8f0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
2b900 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2b910 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
2b920 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
2b930 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2b940 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2b950 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2b960 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
2b970 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
2b980 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
2b990 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
2b9a0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
2b9b0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
2b9c0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
2b9d0 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
2b9e0 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
2b9f0 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
2ba00 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
2ba10 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
2ba20 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2ba30 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
2ba40 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
2ba50 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
2ba60 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
2ba70 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
2ba80 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
2ba90 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
2baa0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
2bab0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
2bac0 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20  .**.** Metadata 
2bad0 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
2bae0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
2baf0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
2bb00 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68  assed as the 5th
2bb10 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65  .** and subseque
2bb20 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
2bb30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
2bb40 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
2bb50 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
2bb60 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
2bb70 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
2bb80 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
2bb90 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
2bba0 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  itted..**.** <bl
2bbb0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2bbc0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2bbd0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
2bbe0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
2bbf0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
2bc00 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
2bc10 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
2bc20 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2bc30 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
2bc40 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
2bc50 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2bc60 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
2bc70 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
2bc80 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
2bc90 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
2bca0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2bcb0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
2bcc0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
2bcd0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
2bce0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
2bcf0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2bd00 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
2bd10 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
2bd20 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
2bd30 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
2bd40 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2bd50 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
2bd60 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
2bd70 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2bd80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2bd90 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69  * The memory poi
2bda0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2bdb0 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2bdc0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2bdd0 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
2bde0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
2bdf0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2be00 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
2be10 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
2be20 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
2be30 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
2be40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
2be50 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
2be60 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
2be70 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2be80 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2be90 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
2bea0 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2beb0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2bec0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2bed0 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2bee0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2bef0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2bf00 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2bf10 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2bf20 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2bf30 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2bf40 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2bf50 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72   column. If ther
2bf60 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
2bf70 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
2bf80 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2bf90 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
2bfa0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2bfb0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2bfc0 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
2bfd0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
2bfe0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
2bff0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
2c000 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2c010 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
2c020 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
2c030 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
2c040 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
2c050 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
2c060 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
2c070 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
2c080 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
2c090 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
2c0a0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
2c0b0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
2c0c0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
2c0d0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
2c0e0 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
2c0f0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
2c100 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
2c110 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2c120 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2c130 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2c140 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
2c150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c160 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
2c170 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
2c180 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
2c190 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
2c1a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
2c1b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2c1c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2c1d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2c1e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2c1f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2c200 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
2c210 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2c220 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
2c230 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
2c240 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c250 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2c260 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
2c270 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c280 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
2c290 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
2c2a0 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
2c2b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
2c2c0 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
2c2d0 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
2c2e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
2c2f0 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
2c300 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
2c310 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
2c320 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
2c330 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
2c340 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
2c350 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
2c360 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
2c370 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
2c380 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
2c390 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
2c3a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c3b0 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2c3c0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2c3d0 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
2c3e0 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
2c3f0 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
2c400 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
2c410 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
2c420 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
2c430 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
2c440 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2c450 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2c460 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
2c470 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2c480 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
2c490 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d  tension {H12600}
2c4a0 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20500>.**.** 
2c4b0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c  This interface l
2c4c0 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65  oads an SQLite e
2c4d0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2c4e0 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20   from the named 
2c4f0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  file..**.** {H12
2c500 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  601} The sqlite3
2c510 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2c520 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2c530 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2c540 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
2c550 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
2c560 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
2c570 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
2c580 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d  ..**.** {H12602}
2c590 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   The entry point
2c5a0 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a   is zProc..**.**
2c5b0 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20   {H12603} zProc 
2c5c0 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69  may be 0, in whi
2c5d0 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65  ch case the name
2c5e0 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f   of the entry po
2c5f0 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  int.**          
2c600 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
2c610 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
2c620 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nit"..**.** {H12
2c630 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33  604} The sqlite3
2c640 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2c650 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ) interface shal
2c660 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
2c670 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
2c680 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
2c690 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2c6a0 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
2c6b0 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48   wrong..**.** {H
2c6c0 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72  12605} If an err
2c6d0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
2c6e0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
2c6f0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
2c700 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c        [sqlite3_l
2c710 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2c720 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2c730 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20   attempt to.**  
2c740 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a          fill *pz
2c750 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
2c760 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
2c770 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
2c780 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61  **          obta
2c790 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2c7a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45  e3_malloc()]. {E
2c7b0 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  ND}  The calling
2c7c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2c7d0 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65        should fre
2c7e0 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
2c7f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c800 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2c810 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73   {H12606} Extens
2c820 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
2c830 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
2c840 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2c850 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2c860 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2c870 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
2c880 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20   this API,.**   
2c890 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73 65         otherwise
2c8a0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
2c8b0 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  e returned..*/.i
2c8c0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
2c8d0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
2c8e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c8f0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
2c900 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
2c910 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
2c920 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
2c930 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
2c940 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
2c950 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
2c960 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
2c970 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
2c980 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
2c990 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
2c9a0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
2c9b0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
2c9c0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
2c9d0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
2c9e0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
2c9f0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
2ca00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2ca10 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2ca20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
2ca30 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35  g {H12620} <S205
2ca40 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  00>.**.** So as 
2ca50 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
2ca60 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
2ca70 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
2ca80 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
2ca90 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
2caa0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
2cab0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
2cac0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
2cad0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
2cae0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
2caf0 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
2cb00 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
2cb10 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
2cb20 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2cb30 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
2cb40 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2cb50 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
2cb60 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
2cb70 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2cb80 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
2cb90 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
2cba0 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  #1863..**.** {H1
2cbb0 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73  2621} Call the s
2cbc0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2cbd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
2cbe0 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
2cbf0 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20  f==1.**         
2cc00 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
2cc10 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
2cc20 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
2cc30 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
2cc40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 62  **          it b
2cc50 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
2cc60 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78  *.** {H12622} Ex
2cc70 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2cc80 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
2cc90 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2cca0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2ccb0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
2ccc0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
2ccd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cce0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
2ccf0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
2cd00 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30  ns {H12640} <S20
2cd10 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2cd20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
2cd30 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
2cd40 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
2cd50 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
2cd60 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
2cd70 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
2cd80 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
2cd90 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
2cda0 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74   to all new [dat
2cdb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cdc0 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  s]. {END}.**.** 
2cdd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
2cde0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
2cdf0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2ce00 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20  n an array that 
2ce10 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  is.** obtained f
2ce20 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2ce30 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20  loc()].  If you 
2ce40 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
2ce50 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20  k checker.** on 
2ce60 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
2ce70 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
2ce80 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
2ce90 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65  is array, invoke
2cea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ceb0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2cec0 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68  n()] prior to sh
2ced0 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74  utdown to free t
2cee0 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a  he memory..**.**
2cef0 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 66   {H12641} This f
2cf00 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
2cf10 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  s an extension e
2cf20 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
2cf30 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  is.**          a
2cf40 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2cf50 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2cf60 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
2cf70 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  nnection].**    
2cf80 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20        is opened 
2cf90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
2cfa0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2cfb0 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
2cfc0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2cfd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
2cfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44  **.** {H12642} D
2cff0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
2d000 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
2d010 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
2d020 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
2d030 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69       multiple ti
2d040 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2d050 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
2d060 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  armless..**.** {
2d070 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75  H12643} This rou
2d080 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
2d090 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
2d0a0 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
2d0b0 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ay.**          t
2d0c0 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
2d0d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d0e0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lloc()]..**.** {
2d0f0 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69  H12644} Automati
2d100 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70  c extensions app
2d110 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68  ly across all th
2d120 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  reads..*/.int sq
2d130 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
2d140 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74  sion(void (*xEnt
2d150 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b  ryPoint)(void));
2d160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d170 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
2d180 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
2d190 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32  ing {H12660} <S2
2d1a0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2d1b0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2d1c0 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  es all previousl
2d1d0 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74  y registered aut
2d1e0 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73  omatic.** extens
2d1f0 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20  ions. {END}  It 
2d200 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
2d210 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a  t of all prior.*
2d220 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  * [sqlite3_auto_
2d230 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c  extension()] cal
2d240 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36  ls..**.** {H1266
2d250 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  1} This function
2d260 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
2d270 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2d280 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
2d290 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
2d2a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ions..**.** {H12
2d2b0 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69  662} This functi
2d2c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
2d2d0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2d2e0 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
2d2f0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2d300 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
2d310 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
2d320 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
2d330 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
2d340 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
2d350 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
2d360 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65  ******.**.** The
2d370 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
2d380 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2d390 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
2d3a0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
2d3b0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
2d3c0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
2d3d0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
2d3e0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
2d3f0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
2d400 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
2d410 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
2d420 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
2d430 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
2d440 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
2d450 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
2d460 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
2d470 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
2d480 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
2d490 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
2d4a0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
2d4b0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
2d4c0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
2d4d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
2d4e0 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
2d4f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
2d500 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
2d510 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2d520 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
2d530 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
2d540 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2d550 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
2d560 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
2d570 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2d580 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
2d590 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2d5a0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
2d5b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
2d5c0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
2d5d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d5e0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
2d5f0 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d   Object {H18000}
2d600 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2d610 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
2d620 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
2d630 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20  able module}.** 
2d640 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
2d650 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
2d660 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
2d670 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
2d680 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
2d690 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
2d6a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d6b0 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
2d6c0 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
2d6d0 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
2d6e0 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
2d6f0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
2d700 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ule..**.** A vir
2d710 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2d720 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
2d730 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
2d740 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
2d750 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
2d760 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
2d770 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
2d780 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
2d790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2d7a0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
2d7b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d7c0 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
2d7d0 20 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f   The registratio
2d7e0 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
2d7f0 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
2d800 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
2d810 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
2d820 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
2d830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d840 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
2d850 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
2d860 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
2d870 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
2d880 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
2d890 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
2d8a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d8b0 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
2d8c0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
2d8d0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
2d8e0 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
2d8f0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
2d900 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
2d910 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
2d920 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
2d930 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
2d940 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2d950 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
2d960 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
2d970 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
2d980 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
2d990 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2d9a0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
2d9b0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
2d9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
2d9d0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
2d9e0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
2d9f0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
2da00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2da10 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
2da20 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
2da30 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
2da40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2da50 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2da60 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
2da70 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2da80 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
2da90 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2daa0 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
2dab0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
2dac0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
2dad0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
2dae0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2daf0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
2db00 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2db10 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
2db20 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
2db30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2db40 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
2db50 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
2db60 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
2db70 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2db80 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2db90 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
2dba0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2dbb0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
2dbc0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2dbd0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
2dbe0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
2dbf0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
2dc00 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2dc10 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2dc20 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
2dc30 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
2dc40 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
2dc50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2dc60 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2dc70 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
2dc80 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
2dc90 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2dca0 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
2dcb0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2dcc0 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
2dcd0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2dce0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2dcf0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
2dd00 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2dd10 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
2dd20 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
2dd30 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
2dd40 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
2dd50 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
2dd60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd70 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
2dd80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2dd90 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2dda0 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
2ddb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2ddc0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
2ddd0 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
2dde0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
2ddf0 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
2de00 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
2de10 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2de20 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
2de30 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31   Information {H1
2de40 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8100} <S20400>.*
2de50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2de60 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
2de70 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2de80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2de90 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
2dea0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
2deb0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
2dec0 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
2ded0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
2dee0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
2def0 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
2df00 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
2df10 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
2df20 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2df30 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
2df40 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
2df50 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
2df60 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
2df70 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
2df80 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
2df90 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
2dfa0 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
2dfb0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
2dfc0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f  s..**.** The aCo
2dfd0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
2dfe0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
2dff0 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
2e000 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
2e010 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
2e020 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
2e030 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
2e040 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
2e050 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
2e060 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72    The particular
2e070 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
2e080 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
2e090 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65  raint[].op.  The
2e0a0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2e0b0 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
2e0c0 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74  n.** aConstraint
2e0d0 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f  [].iColumn.  aCo
2e0e0 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
2e0f0 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
2e100 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
2e110 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
2e120 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
2e130 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
2e140 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
2e150 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
2e160 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a  e if it cannot..
2e170 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69  **.** The optimi
2e180 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
2e190 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
2e1a0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
2e1b0 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
2e1c0 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
2e1d0 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
2e1e0 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
2e1f0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
2e200 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
2e210 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
2e220 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
2e230 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
2e240 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
2e250 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
2e260 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
2e270 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
2e280 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  se terms in the 
2e290 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20  correct.** form 
2e2a0 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68  that refer to th
2e2b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
2e2c0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
2e2d0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
2e2e0 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  Information abou
2e2f0 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  t the ORDER BY c
2e300 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20  lause is stored 
2e310 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a  in aOrderBy[]..*
2e320 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61  * Each term of a
2e330 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
2e340 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
2e350 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
2e360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
2e370 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
2e380 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
2e390 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
2e3a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2e3b0 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
2e3c0 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
2e3d0 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72   xFilter.  If ar
2e3e0 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
2e3f0 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
2e400 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
2e410 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
2e420 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
2e430 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
2e440 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
2e450 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
2e460 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72  rgv.  If aConstr
2e470 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
2e480 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
2e490 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
2e4a0 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
2e4b0 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
2e4c0 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
2e4d0 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
2e4e0 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
2e4f0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
2e500 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  * The idxNum and
2e510 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
2e520 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
2e530 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
2e540 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
2e550 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hod..** [sqlite3
2e560 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
2e570 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
2e580 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a  if and only iff.
2e590 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
2e5a0 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
2e5b0 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
2e5c0 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
2e5d0 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
2e5e0 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
2e5f0 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
2e600 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
2e610 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
2e620 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2e630 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
2e640 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
2e650 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
2e660 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74  d..**.** The est
2e670 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
2e680 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
2e690 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
2e6a0 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
2e6b0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
2e6c0 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
2e6d0 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
2e6e0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
2e6f0 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
2e700 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
2e710 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
2e720 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
2e730 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
2e740 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
2e750 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
2e760 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2e770 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
2e780 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
2e790 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
2e7a0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
2e7b0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
2e7c0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
2e7d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2e7e0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
2e7f0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
2e800 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
2e810 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
2e820 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
2e830 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
2e840 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
2e850 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
2e860 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
2e870 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
2e880 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
2e890 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
2e8a0 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
2e8b0 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
2e8c0 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
2e8d0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
2e8e0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
2e8f0 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
2e900 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
2e910 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
2e920 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
2e930 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
2e940 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
2e950 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
2e960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e970 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
2e980 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
2e990 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
2e9a0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2e9b0 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
2e9c0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
2e9d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
2e9e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
2e9f0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
2ea00 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
2ea10 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
2ea20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
2ea30 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
2ea40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2ea50 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
2ea60 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
2ea70 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
2ea80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2ea90 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
2eaa0 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
2eab0 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
2eac0 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
2ead0 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
2eae0 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
2eaf0 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
2eb00 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
2eb10 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
2eb20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
2eb30 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
2eb40 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
2eb50 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
2eb60 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
2eb70 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
2eb80 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
2eb90 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
2eba0 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
2ebb0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
2ebc0 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
2ebd0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
2ebe0 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
2ebf0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
2ec00 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
2ec10 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
2ec20 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
2ec30 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
2ec40 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
2ec50 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
2ec60 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
2ec70 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
2ec80 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
2ec90 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
2eca0 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
2ecb0 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
2ecc0 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
2ecd0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2ece0 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
2ecf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2ed00 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
2ed10 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ed20 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2ed30 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
2ed40 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2ed50 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
2ed60 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
2ed70 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2ed80 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
2ed90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2eda0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
2edb0 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
2edc0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
2edd0 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
2ede0 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
2edf0 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30   {H18200} <S2040
2ee00 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
2ee10 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  AL.**.** This ro
2ee20 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
2ee30 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
2ee40 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2ee50 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20  odule] name..** 
2ee60 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
2ee70 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
2ee80 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
2ee90 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
2eea0 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
2eeb0 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65  he module, or be
2eec0 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
2eed0 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
2eee0 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
2eef0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
2ef00 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d  * The module nam
2ef10 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
2ef20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
2ef30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
2ef40 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
2ef50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2ef60 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  .  The name of t
2ef70 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76  he module is giv
2ef80 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65  en by the .** se
2ef90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
2efa0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2efb0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
2efc0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  r to.** the impl
2efd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2efe0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
2eff0 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20   module].   The 
2f000 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
2f010 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2f020 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ary client data 
2f030 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
2f040 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
2f050 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65  * into the [xCre
2f060 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
2f070 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ct] methods of t
2f080 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2f090 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20   module.** when 
2f0a0 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  a new virtual ta
2f0b0 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20  ble is be being 
2f0c0 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69  created or reini
2f0d0 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  tialized..**.** 
2f0e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 68  This interface h
2f0f0 61 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  as exactly the s
2f100 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 63 61  ame effect as ca
2f110 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  lling.** [sqlite
2f120 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
2f130 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c  v2()] with a NUL
2f140 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65  L client data de
2f150 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c  structor..*/.SQL
2f160 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
2f170 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2f180 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
2f190 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2f1a0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
2f1b0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
2f1c0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
2f1d0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
2f1e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
2f1f0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
2f200 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
2f210 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
2f220 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
2f230 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2f240 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
2f250 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
2f260 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
2f270 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
2f280 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
2f290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f2a0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
2f2b0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
2f2c0 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30  entation {H18210
2f2d0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
2f2e0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2f2f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
2f300 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68   identical to th
2f310 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2f320 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68  e_module()] meth
2f330 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  od,.** except th
2f340 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 78 74  at it has an ext
2f350 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ra parameter to 
2f360 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 65  specify .** a de
2f370 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
2f380 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e 74  n for the client
2f390 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20   data pointer.  
2f3a0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
2f3b0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f3c0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
2f3d0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2f3e0 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
2f3f0 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
2f400 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
2f410 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53   pointer.  .*/.S
2f420 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
2f430 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
2f440 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
2f450 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2f460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f470 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
2f480 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
2f490 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
2f4a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2f4b0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
2f4c0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
2f4d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
2f4e0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
2f4f0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
2f500 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
2f510 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
2f520 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a,         /* Cl
2f530 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
2f540 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
2f550 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
2f560 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
2f570 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
2f580 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
2f590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f5a0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2f5b0 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
2f5c0 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34  t {H18010} <S204
2f5d0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2f5e0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a   sqlite3_vtab.**
2f5f0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2f600 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
2f610 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
2f620 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f630 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a  uses a subclass.
2f640 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ** of the follow
2f650 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
2f660 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
2f670 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
2f680 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
2f690 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
2f6a0 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
2f6b0 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
2f6c0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
2f6d0 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
2f6e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f6f0 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
2f700 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
2f710 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
2f720 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
2f730 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
2f740 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
2f750 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2f760 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  ..**.** Virtual 
2f770 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
2f780 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
2f790 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
2f7a0 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
2f7b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2f7c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
2f7d0 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
2f7e0 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
2f7f0 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
2f800 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
2f810 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
2f820 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
2f830 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
2f840 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
2f850 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
2f860 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65  o zErrMsg.  Afte
2f870 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
2f880 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
2f890 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
2f8a0 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
2f8b0 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
2f8c0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2f8d0 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
2f8e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
2f8f0 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
2f900 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
2f910 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
2f920 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
2f930 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
2f940 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
2f950 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
2f960 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
2f970 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
2f980 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
2f990 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
2f9a0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
2f9b0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
2f9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f9d0 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
2f9e0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
2f9f0 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
2fa00 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
2fa10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
2fa20 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
2fa30 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
2fa40 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
2fa50 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
2fa60 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
2fa70 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d  Object  {H18020}
2fa80 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
2fa90 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
2faa0 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
2fab0 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
2fac0 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
2fad0 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  L.**.** Every [v
2fae0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2faf0 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
2fb00 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
2fb10 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
2fb20 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
2fb30 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
2fb40 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
2fb50 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
2fb60 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
2fb70 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
2fb80 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
2fb90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
2fba0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
2fbb0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
2fbc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
2fbd0 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
2fbe0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
2fbf0 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
2fc00 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
2fc10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
2fc20 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
2fc30 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73  e] method.  Cuss
2fc40 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
2fc50 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
2fc60 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
2fc70 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
2fc80 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
2fc90 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
2fca0 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
2fcb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2fcc0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
2fcd0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
2fce0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
2fcf0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
2fd00 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
2fd10 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
2fd20 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
2fd30 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
2fd40 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
2fd50 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
2fd60 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
2fd70 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
2fd80 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
2fd90 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
2fda0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
2fdb0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
2fdc0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
2fdd0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
2fde0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
2fdf0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
2fe00 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
2fe10 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
2fe20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
2fe30 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
2fe40 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
2fe50 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31  irtual Table {H1
2fe60 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8280} <S20400>.*
2fe70 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2fe80 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74  *.** The [xCreat
2fe90 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
2fea0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
2feb0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2fec0 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
2fed0 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
2fee0 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
2fef0 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
2ff00 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
2ff10 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
2ff20 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
2ff30 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
2ff40 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  lement..*/.SQLIT
2ff50 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
2ff60 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
2ff70 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
2ff80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
2ff90 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
2ffa0 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
2ffb0 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
2ffc0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48  Virtual Table {H
2ffd0 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18300} <S20400>.
2ffe0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2fff0 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
30000 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
30010 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
30020 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30030 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
30040 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
30050 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
30060 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
30070 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
30080 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
30090 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
300a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
300b0 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
300c0 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
300d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
300e0 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
300f0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
30100 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
30110 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
30120 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
30130 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
30140 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
30150 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
30160 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
30170 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
30180 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
30190 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
301a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
301b0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
301c0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
301d0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
301e0 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
301f0 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
30200 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
30210 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
30220 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
30230 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
30240 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
30250 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
30260 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
30270 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
30280 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
30290 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
302a0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
302b0 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
302c0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
302d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
302e0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
302f0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
30300 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
30310 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
30320 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
30330 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
30340 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
30350 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
30360 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
30370 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
30380 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
30390 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
303a0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
303b0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
303c0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
303d0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
303e0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
303f0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
30400 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
30410 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30420 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30430 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
30440 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
30450 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
30460 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
30470 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
30480 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
30490 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
304a0 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
304b0 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
304c0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
304d0 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
304e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
304f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
30500 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
30510 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d  en BLOB {H17800}
30520 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59   <S30230>.** KEY
30530 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
30540 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
30550 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
30560 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
30570 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
30580 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
30590 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
305a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
305b0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
305c0 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
305d0 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73  rmed..** Objects
305e0 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
305f0 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
30600 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
30610 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
30620 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
30630 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
30640 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
30650 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
30660 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
30670 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
30680 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
30690 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
306a0 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
306b0 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
306c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
306d0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
306e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
306f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
30700 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a   BLOB in bytes..
30710 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
30720 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
30730 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
30740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
30750 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
30760 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48  cremental I/O {H
30770 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17810} <S30230>.
30780 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
30790 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
307a0 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
307b0 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
307c0 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
307d0 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
307e0 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
307f0 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
30800 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
30810 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
30820 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
30830 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
30840 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
30850 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
30860 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
30870 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
30880 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
30890 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
308a0 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
308b0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
308c0 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42 4c 4f  ero, the the BLO
308d0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
308e0 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
308f0 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20  e access. If it 
30900 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
30910 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
30920 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  read access..**.
30930 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
30940 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
30950 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
30960 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
30970 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
30980 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
30990 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
309a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
309b0 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65  at.** is assigne
309c0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
309d0 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64  ase is connected
309e0 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e   using [ATTACH].
309f0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e  .** For the main
30a00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
30a10 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
30a20 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20  e is "main"..** 
30a30 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
30a40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
30a50 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
30a60 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
30a70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
30a80 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
30a90 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
30aa0 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
30ab0 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
30ac0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
30ad0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
30ae0 64 20 61 6e 64 20 61 6e 79 20 76 61 6c 75 65 20  d and any value 
30af0 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
30b00 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74  pBlob should not
30b10 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20   be used by the 
30b20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20  caller..** This 
30b30 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
30b40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30b50 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f  ection] error co
30b60 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
30b70 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
30b80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
30b90 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30ba0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a  3_errmsg()]..**.
30bb0 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74 68  ** If the row th
30bc0 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
30bd0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
30be0 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
30bf0 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
30c00 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
30c10 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
30c20 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
30c30 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
30c40 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
30c50 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
30c60 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
30c70 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
30c80 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
30c90 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
30ca0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
30cb0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
30cc0 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c   open on..** Cal
30cd0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
30ce0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
30cf0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
30d00 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20  ite()] for.** a 
30d10 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e  expired BLOB han
30d20 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e  dle fail with an
30d30 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
30d40 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
30d50 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74 74  ** Changes writt
30d60 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70  en into a BLOB p
30d70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42  rior to the BLOB
30d80 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f   expiring are no
30d90 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79  t.** rollback by
30da0 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
30db0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
30dc0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
30dd0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
30de0 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
30df0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
30e00 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
30e10 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
30e20 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d  nts:.** [H17813]
30e30 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31   [H17814] [H1781
30e40 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37  6] [H17819] [H17
30e50 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f  821] [H17824].*/
30e60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
30e70 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
30e80 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
30e90 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
30ea0 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
30eb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
30ec0 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
30ed0 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
30ee0 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
30ef0 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
30f00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30f10 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
30f20 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20  Handle {H17830} 
30f30 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S30230>.**.** C
30f40 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
30f50 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
30f60 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  ** Closing a BLO
30f70 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
30f80 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
30f90 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
30fa0 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
30fb0 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
30fc0 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
30fd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
30fe0 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
30ff0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
31000 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
31010 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e   mode]..** If an
31020 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
31030 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
31040 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
31050 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
31060 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
31070 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
31080 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d   will fit. {END}
31090 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74  .**.** Closing t
310a0 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f  he BLOB often fo
310b0 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73  rces the changes
310c0 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20  .** out to disk 
310d0 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f  and so if any I/
310e0 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20  O errors occur, 
310f0 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  they will likely
31100 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65   occur.** at the
31110 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42   time when the B
31120 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  LOB is closed.  
31130 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 65 72 72  {H17833} Any err
31140 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
31150 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
31160 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
31170 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
31180 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  rn value..**.** 
31190 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  The BLOB is clos
311a0 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c  ed unconditional
311b0 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69  ly.  Even if thi
311c0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
311d0 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  s.** an error co
311e0 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  de, the BLOB is 
311f0 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a  still closed..**
31200 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
31210 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48  :.** [H17833] [H
31220 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a  17836] [H17839].
31230 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
31240 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  lob_close(sqlite
31250 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
31260 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
31270 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
31280 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37  n Open BLOB {H17
31290 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  840} <S30230>.**
312a0 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20  .** Returns the 
312b0 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66  size in bytes of
312c0 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73   the BLOB access
312d0 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65  ible via the ope
312e0 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 61 6e 64  n.** []BLOB hand
312f0 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
31300 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31310 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
31320 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74   [H17843].*/.int
31330 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
31340 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
31350 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
31360 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20  3REF: Read Data 
31370 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72  From A BLOB Incr
31380 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35  ementally {H1785
31390 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
313a0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
313b0 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  is used to read 
313c0 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65  data from an ope
313d0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
313e0 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  into a.** caller
313f0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
31400 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  . N bytes of dat
31410 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
31420 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72  o buffer Z.** fr
31430 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  om the open BLOB
31440 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
31450 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
31460 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
31470 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
31480 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
31490 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
314a0 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
314b0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
314c0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
314d0 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72  s read.  If N or
314e0 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
314f0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
31500 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
31510 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
31520 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
31530 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20  *.** An attempt 
31540 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20  to read from an 
31550 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
31560 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
31570 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
31580 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
31590 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  RT]..**.** On su
315a0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
315b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
315c0 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b   Otherwise, an [
315d0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
315e0 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
315f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
31600 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ned..**.** Requi
31610 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
31620 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48  853] [H17856] [H
31630 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20  17859] [H17862] 
31640 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35  [H17863] [H17865
31650 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e  ] [H17868].*/.in
31660 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
31670 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
31680 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
31690 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
316a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
316b0 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
316c0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
316d0 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d  entally {H17870}
316e0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
316f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
31700 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
31710 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
31720 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
31730 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  rom a.** caller-
31740 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
31750 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
31760 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
31770 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
31780 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
31790 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
317a0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
317b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42  .**.** If the [B
317c0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
317d0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
317e0 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
317f0 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
31800 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
31810 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
31820 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
31830 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
31840 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
31850 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
31860 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
31870 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
31880 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
31890 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
318a0 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a  the BLOB; it is.
318b0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
318c0 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
318d0 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75  size of a BLOB u
318e0 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
318f0 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
31900 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
31910 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
31920 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
31930 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
31940 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
31950 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
31960 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69  written.  If N i
31970 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
31980 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ero [SQLITE_ERRO
31990 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
319a0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
319b0 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  itten..**.** An 
319c0 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  attempt to write
319d0 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b   to an expired [
319e0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
319f0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
31a00 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
31a10 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69  ITE_ABORT].  Wri
31a20 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  tes to the BLOB 
31a30 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a  that occurred.**
31a40 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f   before the [BLO
31a50 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65  B handle] expire
31a60 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64  d are not rolled
31a70 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20   back by the.** 
31a80 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
31a90 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68  e handle, though
31aa0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65   of course those
31ab0 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a   changes might.*
31ac0 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72  * have been over
31ad0 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73  written by the s
31ae0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78  tatement that ex
31af0 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68  pired the BLOB h
31b00 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f  andle.** or by o
31b10 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74  ther independent
31b20 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
31b30 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
31b40 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
31b50 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
31b60 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63  se, an  [error c
31b70 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65  ode] or an [exte
31b80 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
31b90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
31ba0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
31bb0 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48  :.** [H17873] [H
31bc0 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20  17874] [H17875] 
31bd0 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37  [H17876] [H17877
31be0 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38  ] [H17879] [H178
31bf0 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20  82] [H17885].** 
31c00 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20  [H17888].*/.int 
31c10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
31c20 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  te(sqlite3_blob 
31c30 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  *, const void *z
31c40 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
31c50 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
31c60 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
31c70 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65  File System Obje
31c80 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32  cts {H11200} <S2
31c90 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69  0100>.**.** A vi
31ca0 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d  rtual filesystem
31cb0 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71   (VFS) is an [sq
31cc0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
31cd0 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  t.** that SQLite
31ce0 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63   uses to interac
31cf0 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e  t.** with the un
31d00 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
31d10 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74  ng system.  Most
31d20 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63   SQLite builds c
31d30 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69  ome with a.** si
31d40 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53  ngle default VFS
31d50 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72   that is appropr
31d60 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73  iate for the hos
31d70 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e  t computer..** N
31d80 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ew VFSes can be 
31d90 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65  registered and e
31da0 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61  xisting VFSes ca
31db0 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65  n be unregistere
31dc0 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  d..** The follow
31dd0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61  ing interfaces a
31de0 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a  re provided..**.
31df0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
31e00 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66  fs_find() interf
31e10 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
31e20 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67  inter to a VFS g
31e30 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a  iven its name..*
31e40 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65  * Names are case
31e50 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e   sensitive..** N
31e60 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
31e70 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
31e80 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68  trings..** If th
31e90 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
31ea0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31eb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
31ec0 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e  If zVfsName is N
31ed0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66  ULL then the def
31ee0 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75  ault VFS is retu
31ef0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  rned..**.** New 
31f00 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
31f10 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
31f20 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
31f30 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46  ..** Each new VF
31f40 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65  S becomes the de
31f50 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65  fault VFS if the
31f60 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69   makeDflt flag i
31f70 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61  s set..** The sa
31f80 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65  me VFS can be re
31f90 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
31fa0 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20  e times without 
31fb0 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61  injury..** To ma
31fc0 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56  ke an existing V
31fd0 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61  FS into the defa
31fe0 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65  ult VFS, registe
31ff0 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69  r it again.** wi
32000 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  th the makeDflt 
32010 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77  flag set.  If tw
32020 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65  o different VFSe
32030 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61  s with the.** sa
32040 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69  me name are regi
32050 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61  stered, the beha
32060 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
32070 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20  d.  If a.** VFS 
32080 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
32090 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69  th a name that i
320a0 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
320b0 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68  ty string,.** th
320c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
320d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
320e0 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61  .** Unregister a
320f0 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71   VFS with the sq
32100 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
32110 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  ster() interface
32120 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61  ..** If the defa
32130 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67  ult VFS is unreg
32140 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72  istered, another
32150 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61   VFS is chosen a
32160 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  s.** the default
32170 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f  .  The choice fo
32180 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73  r the new VFS is
32190 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
321a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
321b0 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31  ** [H11203] [H11
321c0 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48  206] [H11209] [H
321d0 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20  11212] [H11215] 
321e0 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69  [H11218].*/.sqli
321f0 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
32200 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
32210 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
32220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
32230 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
32240 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
32250 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
32260 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
32270 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
32280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32290 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30  : Mutexes {H1700
322a0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
322b0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
322c0 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  e uses these rou
322d0 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64  tines for thread
322e0 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74  .** synchronizat
322f0 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79  ion. Though they
32300 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
32310 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73  r internal.** us
32320 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64  e by SQLite, cod
32330 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
32340 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a  inst SQLite is.*
32350 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75  * permitted to u
32360 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  se any of these 
32370 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
32380 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63  The SQLite sourc
32390 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20  e code contains 
323a0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
323b0 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74  ntations.** of t
323c0 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69  hese mutex routi
323d0 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72  nes.  An appropr
323e0 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iate implementat
323f0 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74  ion.** is select
32400 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
32410 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
32420 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
32430 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
32440 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
32450 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
32460 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
32470 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
32480 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
32490 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
324a0 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
324b0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
324c0 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
324d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
324e0 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  P.** </ul>.**.**
324f0 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
32500 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
32510 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
32520 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
32530 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
32540 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
32550 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
32560 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
32570 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
32580 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c  cation.  The SQL
32590 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a  ITE_MUTEX_OS2,.*
325a0 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50  * SQLITE_MUTEX_P
325b0 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49  THREAD, and SQLI
325c0 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70  TE_MUTEX_W32 imp
325d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
325e0 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  are appropriate 
325f0 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c  for use on OS/2,
32600 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f   Unix, and Windo
32610 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c  ws..**.** If SQL
32620 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
32630 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
32640 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65  MUTEX_APPDEF pre
32650 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63  processor.** mac
32660 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68  ro defined (with
32670 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58   "-DSQLITE_MUTEX
32680 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65  _APPDEF=1"), the
32690 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  n no mutex.** im
326a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
326b0 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68  included with th
326c0 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68  e library. In th
326d0 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61  is case the.** a
326e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
326f0 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20  supply a custom 
32700 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
32710 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a  tion using the.*
32720 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
32730 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f  _MUTEX] option o
32740 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  f the sqlite3_co
32750 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a  nfig() function.
32760 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  ** before callin
32770 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  g sqlite3_initia
32780 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74  lize() or any ot
32790 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74  her public sqlit
327a0 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  e3_.** function 
327b0 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74  that calls sqlit
327c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
327d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20  .**.** {H17011} 
327e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
327f0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  x_alloc() routin
32800 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65  e allocates a ne
32810 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72  w.** mutex and r
32820 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32830 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d   to it. {H17012}
32840 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e   If it returns N
32850 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e  ULL.** that mean
32860 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63  s that a mutex c
32870 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f  ould not be allo
32880 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20  cated. {H17013} 
32890 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75  SQLite.** will u
328a0 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20  nwind its stack 
328b0 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72  and return an er
328c0 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68  ror. {H17014} Th
328d0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
328e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
328f0 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66  lloc() is one of
32900 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
32910 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20  onstants:.**.** 
32920 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
32930 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
32940 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
32950 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
32960 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
32970 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
32980 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  TER.** <li>  SQL
32990 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
329a0 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  _MEM.** <li>  SQ
329b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
329c0 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20  C_MEM2.** <li>  
329d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
329e0 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e  TIC_PRNG.** <li>
329f0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
32a00 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69  TATIC_LRU.** <li
32a10 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
32a20 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c  STATIC_LRU2.** <
32a30 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  /ul>.**.** {H170
32a40 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77  15} The first tw
32a50 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73  o constants caus
32a60 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
32a70 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74  alloc() to creat
32a80 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78  e.** a new mutex
32a90 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78  .  The new mutex
32aa0 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68   is recursive wh
32ab0 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
32ac0 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20  RECURSIVE.** is 
32ad0 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63  used but not nec
32ae0 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e  essarily so when
32af0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
32b00 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44  ST is used. {END
32b10 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  }.** The mutex i
32b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
32b30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
32b40 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
32b50 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
32b60 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
32b70 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
32b80 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
32b90 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
32ba0 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42   to.  {H17016} B
32bb0 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  ut SQLite will o
32bc0 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65  nly request a re
32bd0 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e  cursive mutex in
32be0 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20  .** cases where 
32bf0 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20  it really needs 
32c00 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61  one.  {END} If a
32c10 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75   faster non-recu
32c20 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69  rsive mutex.** i
32c30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
32c40 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68   available on th
32c50 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c  e host platform,
32c60 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79   the mutex subsy
32c70 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65  stem.** might re
32c80 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65  turn such a mute
32c90 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  x in response to
32ca0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
32cb0 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ST..**.** {H1701
32cc0 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c  7} The other all
32cd0 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  owed parameters 
32ce0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
32cf0 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65  _alloc() each re
32d00 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
32d10 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
32d20 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
32d30 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61   {END}  Four sta
32d40 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a  tic mutexes are.
32d50 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63  ** used by the c
32d60 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f  urrent version o
32d70 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72  f SQLite.  Futur
32d80 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
32d90 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20  Lite.** may add 
32da0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
32db0 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74  c mutexes.  Stat
32dc0 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66  ic mutexes are f
32dd0 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
32de0 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c  se by SQLite onl
32df0 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  y.  Applications
32e00 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65   that use SQLite
32e10 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a   mutexes should.
32e20 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20  ** use only the 
32e30 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20  dynamic mutexes 
32e40 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49  returned by SQLI
32e50 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72  TE_MUTEX_FAST or
32e60 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
32e70 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a  _RECURSIVE..**.*
32e80 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20  * {H17018} Note 
32e90 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74  that if one of t
32ea0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
32eb0 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c   parameters (SQL
32ec0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
32ed0 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45  * or SQLITE_MUTE
32ee0 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20  X_RECURSIVE) is 
32ef0 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65  used then sqlite
32f00 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a  3_mutex_alloc().
32f10 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66  ** returns a dif
32f20 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20  ferent mutex on 
32f30 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31  every call.  {H1
32f40 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68  7034} But for th
32f50 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65  e static.** mute
32f60 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d  x types, the sam
32f70 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72  e mutex is retur
32f80 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c  ned on every cal
32f90 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68  l that has.** th
32fa0 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62  e same type numb
32fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  er..**.** {H1701
32fc0 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  9} The sqlite3_m
32fd0 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
32fe0 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
32ff0 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
33000 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
33010 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30  c mutex. {H17020
33020 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65  } SQLite is care
33030 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ful to deallocat
33040 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d  e every.** dynam
33050 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74  ic mutex that it
33060 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37   allocates. {A17
33070 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63  021} The dynamic
33080 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
33090 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77  t be in.** use w
330a0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
330b0 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32  llocated. {A1702
330c0 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  2} Attempting to
330d0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74   deallocate a st
330e0 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65  atic.** mutex re
330f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
33100 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31  ed behavior. {H1
33110 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76  7023} SQLite nev
33120 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
33130 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
33140 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
33150 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
33160 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69  enter() and sqli
33170 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
33180 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
33190 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d  .** to enter a m
331a0 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49  utex. {H17024} I
331b0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
331c0 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68   is already with
331d0 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a  in the mutex,.**
331e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
331f0 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63  nter() will bloc
33200 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  k and sqlite3_mu
33210 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72  tex_try() will r
33220 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
33230 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20  BUSY. {H17025}  
33240 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
33250 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63  x_try() interfac
33260 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
33270 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75  E_OK].** upon su
33280 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
33290 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65   {H17026} Mutexe
332a0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
332b0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
332c0 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65  RECURSIVE can be
332d0 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c   entered multipl
332e0 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73  e times by the s
332f0 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b  ame thread..** {
33300 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20  H17027} In such 
33310 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75  cases the,.** mu
33320 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74  tex must be exit
33330 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62  ed an equal numb
33340 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f  er of times befo
33350 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  re another threa
33360 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20  d.** can enter. 
33370 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65   {A17028} If the
33380 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69   same thread tri
33390 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20  es to enter any 
333a0 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  other.** kind of
333b0 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e   mutex more than
333c0 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76   once, the behav
333d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
333e0 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51  ..** {H17029} SQ
333f0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
33400 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20  exhibit.** such 
33410 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20  behavior in its 
33420 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78  own use of mutex
33430 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73  es..**.** Some s
33440 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d  ystems (for exam
33450 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29  ple, Windows 95)
33460 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
33470 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
33480 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
33490 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
334a0 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73  y().  On those s
334b0 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f  ystems, sqlite3_
334c0 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77  mutex_try().** w
334d0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
334e0 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
334f0 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c  {H17030} The SQL
33500 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76  ite core only ev
33510 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74  er uses.** sqlit
33520 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61  e3_mutex_try() a
33530 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s an optimizatio
33540 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63  n so this is acc
33550 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  eptable behavior
33560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d  ..**.** {H17031}
33570 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
33580 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69  ex_leave() routi
33590 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78  ne exits a mutex
335a0 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65   that was.** pre
335b0 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20  viously entered 
335c0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
335d0 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68  ad.  {A17032} Th
335e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
335f0 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68   undefined if th
33600 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63  e mutex is not c
33610 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
33620 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69   by the.** calli
33630 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20  ng thread or is 
33640 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c  not currently al
33650 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33  located.  {H1703
33660 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  3} SQLite will.*
33670 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
33680 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  r. {END}.**.** I
33690 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
336a0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
336b0 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33  enter(), sqlite3
336c0 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72  _mutex_try(), or
336d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
336e0 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e  x_leave() is a N
336f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
33700 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74  n all three rout
33710 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61  ines.** behave a
33720 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
33730 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33740 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
33750 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75   and [sqlite3_mu
33760 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a  tex_notheld()]..
33770 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
33780 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   *sqlite3_mutex_
33790 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
337a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
337b0 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ree(sqlite3_mute
337c0 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
337d0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71  3_mutex_enter(sq
337e0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69  lite3_mutex*);.i
337f0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
33800 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74  _try(sqlite3_mut
33810 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
33820 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73  e3_mutex_leave(s
33830 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
33840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33850 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f   Mutex Methods O
33860 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c  bject {H17120} <
33870 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52  S20130>.** EXPER
33880 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
33890 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
338a0 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  s structure defi
338b0 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65  nes the low-leve
338c0 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  l routines.** us
338d0 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  ed to allocate a
338e0 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a  nd use mutexes..
338f0 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74  **.** Usually, t
33900 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
33910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
33920 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c   provided by SQL
33930 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69  ite are.** suffi
33940 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74  cient, however t
33950 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20  he user has the 
33960 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69  option of substi
33970 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a  tuting a custom.
33980 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
33990 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65  n for specialize
339a0 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72  d deployments or
339b0 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69   systems for whi
339c0 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65  ch SQLite.** doe
339d0 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  s not provide a 
339e0 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
339f0 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  ntation. In this
33a00 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a   case, the user.
33a10 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70  ** creates and p
33a20 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74  opulates an inst
33a30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
33a40 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a  ucture to pass.*
33a50 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  * to sqlite3_con
33a60 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68  fig() along with
33a70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
33a80 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
33a90 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  n..** Additional
33aa0 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ly, an instance 
33ab0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
33ac0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  e can be used as
33ad0 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61   an.** output va
33ae0 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72  riable when quer
33af0 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20  ying the system 
33b00 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
33b10 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
33b20 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74  ntation, using t
33b30 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
33b40 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69  G_GETMUTEX] opti
33b50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  on..**.** The xM
33b60 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
33b70 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
33b80 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
33b90 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
33ba0 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
33bb0 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
33bc0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
33bd0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
33be0 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78  * {H17001} The x
33bf0 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e  MutexInit routin
33c00 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65  e shall be calle
33c10 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65  d by SQLite once
33c20 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66   for each.** eff
33c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b  ective call to [
33c40 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
33c50 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ze()]..**.** The
33c60 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f   xMutexEnd metho
33c70 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
33c80 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
33c90 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
33ca0 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74  t of system shut
33cb0 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69  down by the sqli
33cc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66  te3_shutdown() f
33cd0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20  unction. The.** 
33ce0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
33cf0 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73  f this method is
33d00 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c   expected to rel
33d10 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e  ease all outstan
33d20 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65  ding.** resource
33d30 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  s obtained by th
33d40 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20  e mutex methods 
33d50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
33d60 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68  especially.** th
33d70 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ose obtained by 
33d80 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  the xMutexInit m
33d90 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20  ethod. {H17003} 
33da0 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a  The xMutexEnd().
33db0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  ** interface sha
33dc0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e  ll be invoked on
33dd0 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c  ce for each call
33de0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   to [sqlite3_shu
33df0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
33e00 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65  The remaining se
33e10 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69  ven methods defi
33e20 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
33e30 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c  cture (xMutexAll
33e40 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65  oc,.** xMutexFre
33e50 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20  e, xMutexEnter, 
33e60 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65  xMutexTry, xMute
33e70 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65  xLeave, xMutexHe
33e80 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78  ld and.** xMutex
33e90 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65  Notheld) impleme
33ea0 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nt the following
33eb0 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73   interfaces (res
33ec0 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a  pectively):.**.*
33ed0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
33ee0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
33ef0 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a  _alloc()] </li>.
33f00 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
33f10 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
33f20 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
33f30 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
33f40 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e  x_enter()] </li>
33f50 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
33f60 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
33f70 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
33f80 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
33f90 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e  x_leave()] </li>
33fa0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
33fb0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
33fc0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
33fd0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
33fe0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f  ex_notheld()] </
33ff0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
34000 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  ** The only diff
34010 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74  erence is that t
34020 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  he public sqlite
34030 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20  3_XXX functions 
34040 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62  enumerated.** ab
34050 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  ove silently ign
34060 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69  ore any invocati
34070 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20  ons that pass a 
34080 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
34090 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c  tead.** of a val
340a0 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e  id mutex handle.
340b0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
340c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68  ions of the meth
340d0 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62  ods defined.** b
340e0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
340f0 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65   are not require
34100 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73  d to handle this
34110 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c   case, the resul
34120 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67  ts.** of passing
34130 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34140 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c  instead of a val
34150 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20  id mutex handle 
34160 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a  are undefined.**
34170 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63   (i.e. it is acc
34180 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69  eptable to provi
34190 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  de an implementa
341a0 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75  tion that segfau
341b0 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20  lts if.** it is 
341c0 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f  passed a NULL po
341d0 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64  inter)..*/.typed
341e0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
341f0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20  3_mutex_methods 
34200 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
34210 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
34220 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
34230 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d  ods {.  int (*xM
34240 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b  utexInit)(void);
34250 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45  .  int (*xMutexE
34260 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c  nd)(void);.  sql
34270 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d  ite3_mutex *(*xM
34280 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b  utexAlloc)(int);
34290 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
342a0 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75  Free)(sqlite3_mu
342b0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
342c0 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71  *xMutexEnter)(sq
342d0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
342e0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72    int (*xMutexTr
342f0 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  y)(sqlite3_mutex
34300 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d   *);.  void (*xM
34310 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74  utexLeave)(sqlit
34320 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69  e3_mutex *);.  i
34330 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29  nt (*xMutexHeld)
34340 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
34350 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
34360 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65  xNotheld)(sqlite
34370 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a  3_mutex *);.};..
34380 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34390 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69  Mutex Verificati
343a0 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37  on Routines {H17
343b0 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53  080} <S20130> <S
343c0 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30800>.**.** The
343d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
343e0 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65  eld() and sqlite
343f0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
34400 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  ) routines.** ar
34410 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
34420 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74  se inside assert
34430 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b  () statements. {
34440 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69  H17081} The SQLi
34450 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72  te core.** never
34460 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
34470 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69  ines except insi
34480 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61  de an assert() a
34490 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  nd applications.
344a0 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74  ** are advised t
344b0 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61  o follow the lea
344c0 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20  d of the core.  
344d0 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72  {H17082} The cor
344e0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
344f0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
34500 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
34510 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
34520 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
34530 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
34540 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38  UG flag.  {A1708
34550 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65  7} External mute
34560 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
34570 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65  s.** are only re
34580 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
34590 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
345a0 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47   if SQLITE_DEBUG
345b0 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61   is.** defined a
345c0 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20  nd if NDEBUG is 
345d0 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  not defined..**.
345e0 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73  ** {H17083} Thes
345f0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
34600 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
34610 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
34620 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
34630 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
34640 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
34650 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
34660 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
34670 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70  {X17084} The imp
34680 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
34690 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ot required to p
346a0 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73  rovided versions
346b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75   of these.** rou
346c0 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61  tines that actua
346d0 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65  lly work. If the
346e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
346f0 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
34700 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73   working.** vers
34710 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f  ions of these ro
34720 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c  utines, it shoul
34730 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69  d at least provi
34740 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c  de stubs that al
34750 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ways.** return t
34760 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20  rue so that one 
34770 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75  does not get spu
34780 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20  rious assertion 
34790 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20  failures..**.** 
347a0 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20  {H17085} If the 
347b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
347c0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
347d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
347e0 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
347f0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
34800 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54  turn 1.  {END} T
34810 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65  his seems counte
34820 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63  r-intuitive sinc
34830 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65  e.** clearly the
34840 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65   mutex cannot be
34850 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73   held if it does
34860 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74   not exist.  But
34870 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73   the.** the reas
34880 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65  on the mutex doe
34890 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62  s not exist is b
348a0 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64  ecause the build
348b0 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67   is not.** using
348c0 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77   mutexes.  And w
348d0 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68  e do not want th
348e0 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61  e assert() conta
348f0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c  ining the.** cal
34900 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  l to sqlite3_mut
34910 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69  ex_held() to fai
34920 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f  l, so a non-zero
34930 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68   return is.** th
34940 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68  e appropriate th
34950 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37  ing to do.  {H17
34960 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33  086} The sqlite3
34970 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
34980 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68  .** interface sh
34990 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e  ould also return
349a0 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20   1 when given a 
349b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
349c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
349d0 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  ex_held(sqlite3_
349e0 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
349f0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
34a00 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
34a10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34a20 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73  REF: Mutex Types
34a30 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30   {H17001} <H1700
34a40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
34a50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
34a60 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  c()] interface t
34a70 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
34a80 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20  gument.** which 
34a90 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
34aa0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
34ab0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74  s..**.** The set
34ac0 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78   of static mutex
34ad0 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  es may change fr
34ae0 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65  om one SQLite re
34af0 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20  lease to the.** 
34b00 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
34b10 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64  ons that overrid
34b20 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  e the built-in m
34b30 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20  utex logic must 
34b40 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74  be.** prepared t
34b50 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64  o accommodate ad
34b60 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
34b70 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66  mutexes..*/.#def
34b80 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
34b90 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20  _FAST           
34ba0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
34bb0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
34bc0 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  VE        1.#def
34bd0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
34be0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20  _STATIC_MASTER  
34bf0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
34c00 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
34c10 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20  MEM       3  /* 
34c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
34c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34c40 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
34c50 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20  MEM2      4  /* 
34c60 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66  NOT USED */.#def
34c70 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
34c80 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20  _STATIC_OPEN    
34c90 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42    4  /* sqlite3B
34ca0 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64  treeOpen() */.#d
34cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34cc0 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20  EX_STATIC_PRNG  
34cd0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
34ce0 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64  3_random() */.#d
34cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
34d00 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20  EX_STATIC_LRU   
34d10 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61      6  /* lru pa
34d20 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69  ge list */.#defi
34d30 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
34d40 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20  STATIC_LRU2     
34d50 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   7  /* lru page 
34d60 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  list */../*.** C
34d70 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
34d80 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20  e the mutex for 
34d90 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
34da0 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c  ction {H17002} <
34db0 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H17000>.**.** Th
34dc0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
34dd0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34de0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
34df0 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a  x] object that .
34e00 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63  ** serializes ac
34e10 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74  cess to the [dat
34e20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34e30 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61  ] given in the a
34e40 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  rgument.** when 
34e50 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
34e60 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a  ode] is Serializ
34e70 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74  ed..** If the [t
34e80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
34e90 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s Single-thread 
34ea0 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  or Multi-thread 
34eb0 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75  then this.** rou
34ec0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
34ed0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
34ee0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
34ef0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28  qlite3_db_mutex(
34f00 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
34f10 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d  * CAPI3REF: Low-
34f20 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66  Level Control Of
34f30 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20   Database Files 
34f40 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30  {H11300} <S30800
34f50 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d  >.**.** {H11301}
34f60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
34f70 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
34f80 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
34f90 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74  direct call to t
34fa0 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  he.** xFileContr
34fb0 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68  ol method for th
34fc0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
34fd0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73  thods] object as
34fe0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
34ff0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
35000 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65  tabase identifie
35010 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
35020 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30  argument. {H1130
35030 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  2} The.** name o
35040 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
35050 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  s the name assig
35060 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62  ned to the datab
35070 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61  ase by the.** <a
35080 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61   href="lang_atta
35090 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c  ch.html">ATTACH<
350a0 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  /a> SQL command 
350b0 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a  that opened the.
350c0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31  ** database. {H1
350d0 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c  1303} To control
350e0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
350f0 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65  se file, use the
35100 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20   name "main".** 
35110 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
35120 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20  r. {H11304} The 
35130 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
35140 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
35150 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61  his routine.** a
35160 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74  re passed direct
35170 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ly through to th
35180 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
35190 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  rd parameters of
351a0 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  .** the xFileCon
351b0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48  trol method.  {H
351c0 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72  11305} The retur
351d0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78  n value of the x
351e0 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d  FileControl.** m
351f0 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68  ethod becomes th
35200 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
35210 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
35220 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49  **.** {H11306} I
35230 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
35240 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29  ameter (zDbName)
35250 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
35260 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a  the name of any.
35270 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  ** open database
35280 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49   file, then SQLI
35290 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75  TE_ERROR is retu
352a0 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54  rned. {H11307} T
352b0 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  his error.** cod
352c0 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65  e is not remembe
352d0 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74  red and will not
352e0 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20   be recalled by 
352f0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
35300 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
35310 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41  e3_errmsg()]. {A
35320 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72  11308} The under
35330 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72  lying xFileContr
35340 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a  ol method might.
35350 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53  ** also return S
35360 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41  QLITE_ERROR.  {A
35370 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20  11309} There is 
35380 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e  no way to distin
35390 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a  guish between.**
353a0 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44   an incorrect zD
353b0 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c  bName and an SQL
353c0 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e  ITE_ERROR return
353d0 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c   from the underl
353e0 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e  ying.** xFileCon
353f0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e  trol method. {EN
35400 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D}.**.** See als
35410 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  o: [SQLITE_FCNTL
35420 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69  _LOCKSTATE].*/.i
35430 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  nt sqlite3_file_
35440 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a  control(sqlite3*
35450 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
35460 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76  bName, int op, v
35470 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
35480 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20  PI3REF: Testing 
35490 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30  Interface {H1140
354a0 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a  0} <S30800>.**.*
354b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65  * The sqlite3_te
354c0 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74  st_control() int
354d0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
354e0 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72  o read out inter
354f0 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20  nal.** state of 
35500 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e  SQLite and to in
35510 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f  ject faults into
35520 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74   SQLite for test
35530 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e  ing.** purposes.
35540 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
35550 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72  meter is an oper
35560 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20  ation code that 
35570 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68  determines.** th
35580 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e  e number, meanin
35590 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e  g, and operation
355a0 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65   of all subseque
355b0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  nt parameters..*
355c0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
355d0 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75  ace is not for u
355e0 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f  se by applicatio
355f0 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73  ns.  It exists s
35600 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72  olely.** for ver
35610 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65  ifying the corre
35620 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ct operation of 
35630 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
35640 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a  ry.  Depending.*
35650 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c  * on how the SQL
35660 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63  ite library is c
35670 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e  ompiled, this in
35680 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f  terface might no
35690 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  t exist..**.** T
356a0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
356b0 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  e operation code
356c0 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67  s, their meaning
356d0 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  s, the parameter
356e0 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20  s.** they take, 
356f0 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f  and what they do
35700 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74   are all subject
35710 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
35720 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e  ut notice..** Un
35730 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65  like most of the
35740 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69   SQLite API, thi
35750 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
35760 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a  t guaranteed to.
35770 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69  ** operate consi
35780 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65  stently from one
35790 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
357a0 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  next..*/.int sql
357b0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
357c0 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  l(int op, ...);.
357d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
357e0 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61   Testing Interfa
357f0 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64  ce Operation Cod
35800 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31  es {H11410} <H11
35810 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400>.**.** These
35820 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
35830 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69  he valid operati
35840 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65  on code paramete
35850 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68  rs used.** as th
35860 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35870 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73   to [sqlite3_tes
35880 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a  t_control()]..**
35890 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65  .** These parame
358a0 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d  ters and their m
358b0 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a  eanings are subj
358c0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ect to change.**
358d0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
358e0 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61    These values a
358f0 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70  re for testing p
35900 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a  urposes only..**
35910 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
35920 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79  ould not use any
35930 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
35940 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b  ters or the.** [
35950 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
35960 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
35970 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
35980 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52  LITE_TESTCTRL_PR
35990 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20  NG_SAVE         
359a0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
359b0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
359c0 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20  _PRNG_RESTORE   
359d0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
359e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
359f0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20  TRL_PRNG_RESET  
35a00 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
35a10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
35a20 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45  STCTRL_BITVEC_TE
35a30 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ST              
35a40 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
35a50 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f  _TESTCTRL_FAULT_
35a60 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20  INSTALL         
35a70 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
35a80 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e  ITE_TESTCTRL_BEN
35a90 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53  IGN_MALLOC_HOOKS
35aa0 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
35ab0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
35ac0 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20  PENDING_BYTE    
35ad0 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
35ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69  * CAPI3REF: SQLi
35af0 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75  te Runtime Statu
35b00 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32  s {H17200} <S602
35b10 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
35b20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TAL.**.** This i
35b30 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
35b40 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e   to retrieve run
35b50 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f  time status info
35b60 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
35b70 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65   the preformance
35b80 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20   of SQLite, and 
35b90 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65  optionally to re
35ba0 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68  set various.** h
35bb0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20  ighwater marks. 
35bc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
35bd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
35be0 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  r code for.** th
35bf0 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d  e specific param
35c00 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e  eter to measure.
35c10 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74    Recognized int
35c20 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72  eger codes.** ar
35c30 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53  e of the form [S
35c40 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d  QLITE_STATUS_MEM
35c50 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54  ORY_USED | SQLIT
35c60 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a  E_STATUS_...]..*
35c70 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61  * The current va
35c80 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d  lue of the param
35c90 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  eter is returned
35ca0 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e   into *pCurrent.
35cb0 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20  .** The highest 
35cc0 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69  recorded value i
35cd0 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
35ce0 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74  Highwater.  If t
35cf0 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20  he.** resetFlag 
35d00 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
35d10 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64  e highest record
35d20 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20   value is reset 
35d30 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77  after.** *pHighw
35d40 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e  ater is written.
35d50 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73   Some parameters
35d60 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74   do not record t
35d70 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61  he highest.** va
35d80 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20  lue.  For those 
35d90 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f  parameters.** no
35da0 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
35db0 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65   into *pHighwate
35dc0 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46  r and the resetF
35dd0 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  lag is ignored..
35de0 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74  ** Other paramet
35df0 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20  ers record only 
35e00 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
35e10 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63  rk and not the c
35e20 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e  urrent.** value.
35e30 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74    For these latt
35e40 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f  er parameters no
35e50 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
35e60 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e   into *pCurrent.
35e70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35e80 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
35e90 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73  TE_OK on success
35ea0 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a   and a non-zero.
35eb0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
35ec0 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
35ed0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
35ee0 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74  s threadsafe but
35ef0 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20   is not atomic. 
35f00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
35f10 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c  n.** called whil
35f20 65 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 20  e other threads 
35f30 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  are running the 
35f40 73 61 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e  same or differen
35f50 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  t SQLite.** inte
35f60 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35f70 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
35f80 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e  rned in *pCurren
35f90 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77  t and.** *pHighw
35fa0 61 74 65 72 20 72 65 66 6c 65 63 74 20 74 68 65  ater reflect the
35fb0 20 73 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74   status of SQLit
35fc0 65 20 61 74 20 64 69 66 66 65 72 65 6e 74 20 70  e at different p
35fd0 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a  oints in time.**
35fe0 20 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69   and it is possi
35ff0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
36000 20 74 68 72 65 61 64 20 6d 69 67 68 74 20 63 68   thread might ch
36010 61 6e 67 65 20 74 68 65 20 70 61 72 61 6d 65 74  ange the paramet
36020 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e  er.** in between
36030 20 74 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20   the times when 
36040 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70  *pCurrent and *p
36050 48 69 67 68 77 61 74 65 72 20 61 72 65 20 77 72  Highwater are wr
36060 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  itten..**.** See
36070 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36080 64 62 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a  db_status()].*/.
36090 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
360a0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
360b0 73 74 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69  status(int op, i
360c0 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e  nt *pCurrent, in
360d0 74 20 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69  t *pHighwater, i
360e0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
360f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36100 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65   Status Paramete
36110 72 73 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37  rs {H17250} <H17
36120 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  200>.** EXPERIME
36130 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  NTAL.**.** These
36140 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
36150 74 73 20 64 65 73 69 67 6e 61 74 65 20 76 61 72  ts designate var
36160 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74  ious run-time st
36170 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a  atus parameters.
36180 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 72  ** that can be r
36190 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
361a0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a  te3_status()]..*
361b0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
361c0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d  >SQLITE_STATUS_M
361d0 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a  EMORY_USED</dt>.
361e0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
361f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 75 72  meter is the cur
36200 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  rent amount of m
36210 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75  emory checked ou
36220 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  t.** using [sqli
36230 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65  te3_malloc()], e
36240 69 74 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f  ither directly o
36250 72 20 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54  r indirectly.  T
36260 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63  he.** figure inc
36270 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65  ludes calls made
36280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
36290 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 20 61 70  loc()] by the ap
362a0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64  plication.** and
362b0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
362c0 20 75 73 61 67 65 20 62 79 20 74 68 65 20 53 51   usage by the SQ
362d0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53  Lite library.  S
362e0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a  cratch memory.**
362f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b   controlled by [
36300 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
36310 52 41 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c  RATCH] and auxil
36320 69 61 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a  iary page-cache.
36330 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f  ** memory contro
36340 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f  lled by [SQLITE_
36350 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
36360 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] is not include
36370 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72  d in.** this par
36380 61 6d 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f  ameter.  The amo
36390 75 6e 74 20 72 65 74 75 72 6e 65 64 20 69 73 20  unt returned is 
363a0 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61  the sum of the a
363b0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a  llocation.** siz
363c0 65 73 20 61 73 20 72 65 70 6f 72 74 65 64 20 62  es as reported b
363d0 79 20 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68  y the xSize meth
363e0 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  od in [sqlite3_m
363f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64  em_methods].</dd
36400 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36410 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43  TE_STATUS_MALLOC
36420 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _SIZE</dt>.** <d
36430 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72  d>This parameter
36440 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72   records the lar
36450 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  gest memory allo
36460 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a  cation request.*
36470 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  * handed to [sql
36480 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
36490 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
364a0 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a  oc()] (or their.
364b0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69  ** internal equi
364c0 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20  valents).  Only 
364d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
364e0 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48  ed in the.** *pH
364f0 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74  ighwater paramet
36500 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  er to [sqlite3_s
36510 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69  tatus()] is of i
36520 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68  nterest.  .** Th
36530 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20  e value written 
36540 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65  into the *pCurre
36550 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nt parameter is 
36560 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
36570 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
36580 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48  _STATUS_PAGECACH
36590 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_USED</dt>.** <
365a0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
365b0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
365c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 75 73  mber of pages us
365d0 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a  ed out of the.**
365e0 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f   [pagecache memo
365f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68  ry allocator] th
36600 61 74 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65  at was configure
36610 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c  d using .** [SQL
36620 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
36630 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76  ACHE].  The.** v
36640 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
36650 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69   in pages, not i
36660 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  n bytes.</dd>.**
36670 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
36680 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f  TATUS_PAGECACHE_
36690 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a  OVERFLOW</dt>.**
366a0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
366b0 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20  ter returns the 
366c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
366d0 6f 66 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a  of page cache.**
366e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63   allocation whic
366f0 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73  h could not be s
36700 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68 65  tatisfied by the
36710 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
36720 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75  PAGECACHE].** bu
36730 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66  ffer and where f
36740 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f  orced to overflo
36750 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  w to [sqlite3_ma
36760 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a  lloc()].  The.**
36770 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
36780 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74  includes allocat
36790 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c  ions that overfl
367a0 6f 77 65 64 20 62 65 63 61 75 73 65 20 74 68 65  owed because the
367b0 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c  y.** where too l
367c0 61 72 67 65 20 28 74 68 65 79 20 77 65 72 65 20  arge (they were 
367d0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
367e0 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74  "sz" parameter t
367f0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  o.** [SQLITE_CON
36800 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20  FIG_PAGECACHE]) 
36810 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  and allocations 
36820 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20  that overflowed 
36830 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70  because.** no sp
36840 61 63 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20  ace was left in 
36850 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c  the page cache.<
36860 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
36870 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47  QLITE_STATUS_PAG
36880 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e  ECACHE_SIZE</dt>
36890 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72  .** <dd>This par
368a0 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74  ameter records t
368b0 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72  he largest memor
368c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
368d0 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74  uest.** handed t
368e0 6f 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d  o [pagecache mem
368f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20  ory allocator]. 
36900 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20   Only the value 
36910 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a  returned in the.
36920 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70  ** *pHighwater p
36930 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
36940 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69  ite3_status()] i
36950 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20  s of interest.  
36960 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72  .** The value wr
36970 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a  itten into the *
36980 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74  pCurrent paramet
36990 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  er is undefined.
369a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
369b0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43  SQLITE_STATUS_SC
369c0 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a  RATCH_USED</dt>.
369d0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61  ** <dd>This para
369e0 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68  meter returns th
369f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f  e number of allo
36a00 63 61 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74  cations used out
36a10 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61   of the.** [scra
36a20 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tch memory alloc
36a30 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64  ator] configured
36a40 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54   using.** [SQLIT
36a50 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
36a60 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  ].  The value re
36a70 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c  turned is in all
36a80 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a  ocations, not.**
36a90 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63   in bytes.  Sinc
36aa0 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  e a single threa
36ab0 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20  d may only have 
36ac0 6f 6e 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  one scratch allo
36ad0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61  cation.** outsta
36ae0 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74  nding at time, t
36af0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c  his parameter al
36b00 73 6f 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e  so reports the n
36b10 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
36b20 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63  .** using scratc
36b30 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20  h memory at the 
36b40 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a  same time.</dd>.
36b50 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
36b60 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f  _STATUS_SCRATCH_
36b70 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a  OVERFLOW</dt>.**
36b80 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65   <dd>This parame
36b90 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20  ter returns the 
36ba0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36bb0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
36bc0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
36bd0 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20  which could not 
36be0 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79  be statisfied by
36bf0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
36c00 46 49 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20  FIG_SCRATCH].** 
36c10 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 65  buffer and where
36c20 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66   forced to overf
36c30 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  low to [sqlite3_
36c40 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
36c50 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e  values.** return
36c60 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66  ed include overf
36c70 6c 6f 77 73 20 62 65 63 61 75 73 65 20 74 68 65  lows because the
36c80 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63   requested alloc
36c90 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a  ation was too.**
36ca0 20 6c 61 72 67 65 72 20 28 74 68 61 74 20 69 73   larger (that is
36cb0 2c 20 62 65 63 61 75 73 65 20 74 68 65 20 72 65  , because the re
36cc0 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69  quested allocati
36cd0 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 20 74 68  on was larger th
36ce0 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70  an the.** "sz" p
36cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c  arameter to [SQL
36d00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
36d10 43 48 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65  CH]) and because
36d20 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
36d30 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65  er.** slots were
36d40 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c   available..** <
36d50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
36d60 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52  QLITE_STATUS_SCR
36d70 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a  ATCH_SIZE</dt>.*
36d80 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
36d90 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65  eter records the
36da0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20   largest memory 
36db0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
36dc0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20  st.** handed to 
36dd0 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20  [scratch memory 
36de0 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c  allocator].  Onl
36df0 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  y the value retu
36e00 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a  rned in the.** *
36e10 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d  pHighwater param
36e20 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
36e30 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66  _status()] is of
36e40 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20   interest.  .** 
36e50 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65  The value writte
36e60 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72  n into the *pCur
36e70 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69  rent parameter i
36e80 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  s undefined.</dd
36e90 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
36ea0 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52  TE_STATUS_PARSER
36eb0 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c  _STACK</dt>.** <
36ec0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
36ed0 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 64 65  r records the de
36ee0 65 70 65 73 74 20 70 61 72 73 65 72 20 73 74 61  epest parser sta
36ef0 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a  ck.  It is only.
36f00 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ** meaningful if
36f10 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
36f20 6c 65 64 20 77 69 74 68 20 5b 59 59 54 52 41 43  led with [YYTRAC
36f30 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e  KMAXSTACKDEPTH].
36f40 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
36f50 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20  *.** New status 
36f60 70 61 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62  parameters may b
36f70 65 20 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d  e added from tim
36f80 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64  e to time..*/.#d
36f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
36fa0 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20  TUS_MEMORY_USED 
36fb0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
36fc0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ne SQLITE_STATUS
36fd0 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45 44 20  _PAGECACHE_USED 
36fe0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
36ff0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41  SQLITE_STATUS_PA
37000 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57  GECACHE_OVERFLOW
37010 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
37020 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54  ITE_STATUS_SCRAT
37030 43 48 5f 55 53 45 44 20 20 20 20 20 20 20 20 20  CH_USED         
37040 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
37050 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f  _STATUS_SCRATCH_
37060 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23  OVERFLOW     4.#
37070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
37080 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45  ATUS_MALLOC_SIZE
37090 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
370a0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55  ine SQLITE_STATU
370b0 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20  S_PARSER_STACK  
370c0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
370d0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50   SQLITE_STATUS_P
370e0 41 47 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20  AGECACHE_SIZE   
370f0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
37100 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41  LITE_STATUS_SCRA
37110 54 43 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20  TCH_SIZE        
37120 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
37130 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
37140 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b  nection Status {
37150 48 31 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e  H17500} <S60200>
37160 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
37170 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
37180 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
37190 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d   retrieve runtim
371a0 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61  e status informa
371b0 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61  tion .** about a
371c0 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73   single [databas
371d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
371e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
371f0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74  nt is the.** dat
37200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37210 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e   object to be in
37220 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
37230 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37240 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d  .** is the param
37250 65 74 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67  eter to interrog
37260 61 74 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c  ate.  Currently,
37270 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65   the only allowe
37280 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74  d value.** for t
37290 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
372a0 74 65 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ter is [SQLITE_D
372b0 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44  BSTATUS_LOOKASID
372c0 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69  E_USED]..** Addi
372d0 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77  tional options w
372e0 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61  ill likely appea
372f0 72 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  r in future rele
37300 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
37310 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e  **.** The curren
37320 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72  t value of the r
37330 65 71 75 65 73 74 65 64 20 70 61 72 61 6d 65 74  equested paramet
37340 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  er is written in
37350 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20  to *pCur.** and 
37360 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74  the highest inst
37370 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20  antaneous value 
37380 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
37390 2a 70 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20  *pHiwtr.  If.** 
373a0 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20  the resetFlg is 
373b0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68  true, then the h
373c0 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e  ighest instantan
373d0 65 6f 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a  eous value is.**
373e0 20 72 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e   reset back down
373f0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
37400 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  value..**.** See
37410 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
37420 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73  status()] and [s
37430 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74  qlite3_stmt_stat
37440 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  us()]..*/.SQLITE
37450 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
37460 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61  t sqlite3_db_sta
37470 74 75 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  tus(sqlite3*, in
37480 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c  t op, int *pCur,
37490 20 69 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e   int *pHiwtr, in
374a0 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a  t resetFlg);../*
374b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
374c0 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20  atus Parameters 
374d0 66 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  for database con
374e0 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30  nections {H17520
374f0 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58  } <H17500>.** EX
37500 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
37510 20 53 74 61 74 75 73 20 76 65 72 62 73 20 66 6f   Status verbs fo
37520 72 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  r [sqlite3_db_st
37530 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  atus()]..**.** <
37540 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
37550 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41  E_DBSTATUS_LOOKA
37560 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a  SIDE_USED</dt>.*
37570 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d  * <dd>This param
37580 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65  eter returns the
37590 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61   number of looka
375a0 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74  side memory slot
375b0 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63  s currently.** c
375c0 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e  hecked out.</dd>
375d0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
375e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54  fine SQLITE_DBST
375f0 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55  ATUS_LOOKASIDE_U
37600 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a  SED     0.../*.*
37610 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
37620 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 53  ared Statement S
37630 74 61 74 75 73 20 7b 48 31 37 35 35 30 7d 20 3c  tatus {H17550} <
37640 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60200>.** EXPER
37650 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61  IMENTAL.**.** Ea
37660 63 68 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ch prepared stat
37670 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20  ement maintains 
37680 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49  various.** [SQLI
37690 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f  TE_STMTSTATUS_SO
376a0 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74  RT | counters] t
376b0 68 61 74 20 6d 65 61 73 75 72 65 20 74 68 65 20  hat measure the 
376c0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d  number.** of tim
376d0 65 73 20 69 74 20 68 61 73 20 70 65 72 66 6f 72  es it has perfor
376e0 6d 65 64 20 73 70 65 63 69 66 69 63 20 6f 70 65  med specific ope
376f0 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 73 65 20  rations.  These 
37700 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20  counters can.** 
37710 62 65 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74  be used to monit
37720 6f 72 20 74 68 65 20 70 65 72 66 6f 72 6d 61 6e  or the performan
37730 63 65 20 63 68 61 72 61 63 74 65 72 69 73 74 69  ce characteristi
37740 63 73 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  cs of the prepar
37750 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
37760 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
37770 69 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  if the number of
37780 20 74 61 62 6c 65 20 73 74 65 70 73 20 67 72 65   table steps gre
37790 61 74 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a 20  atly exceeds.** 
377a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61  the number of ta
377b0 62 6c 65 20 73 65 61 72 63 68 65 73 20 6f 72 20  ble searches or 
377c0 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 74 68 61  result rows, tha
377d0 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20  t would tend to 
377e0 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 68 61 74  indicate.** that
377f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
37800 61 74 65 6d 65 6e 74 20 69 73 20 75 73 69 6e 67  atement is using
37810 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63   a full table sc
37820 61 6e 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a  an rather than.*
37830 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a  * an index.  .**
37840 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
37850 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ce is used to re
37860 74 72 69 65 76 65 20 61 6e 64 20 72 65 73 65 74  trieve and reset
37870 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 65 73 20   counter values 
37880 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61  from.** a [prepa
37890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
378a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
378b0 65 6e 74 20 69 73 20 74 68 65 20 70 72 65 70 61  ent is the prepa
378c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
378d0 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e   object to be in
378e0 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
378f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37900 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
37910 72 20 63 6f 64 65 20 66 6f 72 20 61 20 73 70 65  r code for a spe
37920 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 53 54  cific [SQLITE_ST
37930 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20  MTSTATUS_SORT | 
37940 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62  counter].** to b
37950 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  e interrogated. 
37960 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20  .** The current 
37970 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71  value of the req
37980 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72 20 69  uested counter i
37990 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
379a0 66 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 69  f the resetFlg i
379b0 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
379c0 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 73 65   counter is rese
379d0 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 65 72 20  t to zero after 
379e0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
379f0 65 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  e call returns..
37a00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
37a10 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
37a20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37a30 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f  db_status()]..*/
37a40 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
37a50 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
37a60 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c  _stmt_status(sql
37a70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
37a80 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29  op,int resetFlg)
37a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37aa0 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65  F: Status Parame
37ab0 74 65 72 73 20 66 6f 72 20 70 72 65 70 61 72 65  ters for prepare
37ac0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d statements {H1
37ad0 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a  7570} <H17550>.*
37ae0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
37af0 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72  *.** These prepr
37b00 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64  ocessor macros d
37b10 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
37b20 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f  des that name co
37b30 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20  unter.** values 
37b40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37b50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
37b60 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65  t_status()] inte
37b70 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65  rface..** The me
37b80 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
37b90 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61  rious counters a
37ba0 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  re as follows:.*
37bb0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
37bc0 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54  >SQLITE_STMTSTAT
37bd0 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50  US_FULLSCAN_STEP
37be0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
37bf0 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  s is the number 
37c00 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 53 51  of times that SQ
37c10 4c 69 74 65 20 68 61 73 20 73 74 65 70 70 65 64  Lite has stepped
37c20 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61   forward in.** a
37c30 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f   table as part o
37c40 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  f a full table s
37c50 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62  can.  Large numb
37c60 65 72 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75  ers for this cou
37c70 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69  nter.** may indi
37c80 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69  cate opportuniti
37c90 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  es for performan
37ca0 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74  ce improvement t
37cb0 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66  hrough .** caref
37cc0 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65  ul use of indice
37cd0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
37ce0 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41  t>SQLITE_STMTSTA
37cf0 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a  TUS_SORT</dt>.**
37d00 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65   <dd>This is the
37d10 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20   number of sort 
37d20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20  operations that 
37d30 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a  have occurred..*
37d40 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c  * A non-zero val
37d50 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ue in this count
37d60 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20  er may indicate 
37d70 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74  an opportunity t
37d80 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74  o.** improvement
37d90 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72   performance thr
37da0 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75 73 65  ough careful use
37db0 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64   of indices.</dd
37dc0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
37dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37de0 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53  STMTSTATUS_FULLS
37df0 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23  CAN_STEP     1.#
37e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
37e10 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20  MTSTATUS_SORT   
37e20 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a             2../*
37e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75  .** CAPI3REF: Cu
37e40 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20  stom Page Cache 
37e50 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49  Object.** EXPERI
37e60 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
37e70 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20   sqlite3_pcache 
37e80 74 79 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20  type is opaque. 
37e90 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74   It is implement
37ea0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75  ed by.** the plu
37eb0 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20  ggable module.  
37ec0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
37ed0 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65  has no knowledge
37ee0 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20   of.** its size 
37ef0 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75  or internal stru
37f00 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20  cture and never 
37f10 64 65 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a  deals with the.*
37f20 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
37f30 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74 20 62   object except b
37f40 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61  y holding and pa
37f50 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a  ssing pointers.*
37f60 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e  * to the object.
37f70 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69  .**.** See [sqli
37f80 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
37f90 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ds] for addition
37fa0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
37fb0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
37fc0 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  t sqlite3_pcache
37fd0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b   sqlite3_pcache;
37fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37ff0 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65  : Application De
38000 66 69 6e 65 64 20 50 61 67 65 20 43 61 63 68 65  fined Page Cache
38010 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  ..** EXPERIMENTA
38020 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  L.**.** The [sql
38030 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
38040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
38050 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66  HE], ...) interf
38060 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73  ace can.** regis
38070 74 65 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ter an alternati
38080 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
38090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20  plementation by 
380a0 70 61 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a  passing in an .*
380b0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
380c0 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  e sqlite3_pcache
380d0 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 63 74 75  _methods structu
380e0 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79  re. The majority
380f0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70   of the .** heap
38100 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20   memory used by 
38110 73 71 6c 69 74 65 20 69 73 20 75 73 65 64 20 62  sqlite is used b
38120 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
38130 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 20 72   to cache data r
38140 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72  ead .** from, or
38150 20 72 65 61 64 79 20 74 6f 20 62 65 20 77 72 69   ready to be wri
38160 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74  tten to, the dat
38170 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69  abase file. By i
38180 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a  mplementing a .*
38190 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  * custom page ca
381a0 63 68 65 20 75 73 69 6e 67 20 74 68 69 73 20 41  che using this A
381b0 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  PI, an applicati
381c0 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d  on can control m
381d0 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c  ore .** precisel
381e0 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  y the amount of 
381f0 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20  memory consumed 
38200 62 79 20 73 71 6c 69 74 65 2c 20 74 68 65 20 77  by sqlite, the w
38210 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20  ay in which .** 
38220 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 73 20 61  said memory is a
38230 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c  llocated and rel
38240 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70  eased, and the p
38250 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f 20  olicies used to 
38260 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78  .** determine ex
38270 61 63 74 6c 79 20 77 68 69 63 68 20 70 61 72 74  actly which part
38280 73 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  s of a database 
38290 66 69 6c 65 20 61 72 65 20 63 61 63 68 65 64 20  file are cached 
382a0 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20  and for .** how 
382b0 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  long..**.** The 
382c0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
382d0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63 6f  structure are co
382e0 70 69 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 72  pied to an inter
382f0 6e 61 6c 20 62 75 66 66 65 72 20 62 79 20 73 71  nal buffer by sq
38300 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 74  lite.** within t
38310 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  he call to [sqli
38320 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a 0a  te3_config]..**.
38330 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 29 20 6d  ** The xInit() m
38340 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20  ethod is called 
38350 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61  once for each ca
38360 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ll to [sqlite3_i
38370 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  nitialize()].** 
38380 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e  (usually only on
38390 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ce during the li
383a0 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 70 72  fetime of the pr
383b0 6f 63 65 73 73 29 2e 20 49 74 20 69 73 20 70 61  ocess). It is pa
383c0 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20 6f  ssed.** a copy o
383d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63  f the sqlite3_pc
383e0 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41 72  ache_methods.pAr
383f0 67 20 76 61 6c 75 65 2e 20 49 74 20 63 61 6e 20  g value. It can 
38400 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 0a 2a  be used to set.*
38410 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 74 72 75  * up global stru
38420 63 74 75 72 65 73 20 61 6e 64 20 6d 75 74 65 78  ctures and mutex
38430 65 73 20 72 65 71 75 69 72 65 64 20 62 79 20 74  es required by t
38440 68 65 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63  he custom page c
38450 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ache .** impleme
38460 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 78 53 68  ntation. The xSh
38470 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20  utdown() method 
38480 69 73 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  is called from w
38490 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  ithin .** [sqlit
384a0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20  e3_shutdown()], 
384b0 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  if the applicati
384c0 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 69 73 20  on invokes this 
384d0 41 50 49 2e 20 49 74 20 63 61 6e 20 62 65 20 75  API. It can be u
384e0 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 61 6e 20  sed.** to clean 
384f0 75 70 20 61 6e 79 20 6f 75 74 73 74 61 6e 64 69  up any outstandi
38500 6e 67 20 72 65 73 6f 75 72 63 65 73 20 62 65 66  ng resources bef
38510 6f 72 65 20 70 72 6f 63 65 73 73 20 73 68 75 74  ore process shut
38520 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 69 72 65  down, if require
38530 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  d..**.** The xCr
38540 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20 69 73  eate() method is
38550 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
38560 63 74 20 61 20 6e 65 77 20 63 61 63 68 65 20 69  ct a new cache i
38570 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a 2a 2a 20  nstance. The.** 
38580 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2c  first parameter,
38590 20 73 7a 50 61 67 65 2c 20 69 73 20 74 68 65 20   szPage, is the 
385a0 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66  size in bytes of
385b0 20 74 68 65 20 70 61 67 65 73 20 74 68 61 74 20   the pages that 
385c0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f 63  must.** be alloc
385d0 61 74 65 64 20 62 79 20 74 68 65 20 63 61 63 68  ated by the cach
385e0 65 2e 20 73 7a 50 61 67 65 20 77 69 6c 6c 20 6e  e. szPage will n
385f0 6f 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66  ot be a power of
38600 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 73 65 63   two. The.** sec
38610 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 62 50  ond argument, bP
38620 75 72 67 65 61 62 6c 65 2c 20 69 73 20 74 72 75  urgeable, is tru
38630 65 20 69 66 20 74 68 65 20 63 61 63 68 65 20 62  e if the cache b
38640 65 69 6e 67 20 63 72 65 61 74 65 64 20 77 69 6c  eing created wil
38650 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20  l.** be used to 
38660 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
38670 61 67 65 73 20 72 65 61 64 20 66 72 6f 6d 20 61  ages read from a
38680 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f 6e 20   file stored on 
38690 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73  disk, or.** fals
386a0 65 20 69 66 20 69 74 20 69 73 20 75 73 65 64 20  e if it is used 
386b0 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79  for an in-memory
386c0 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 63   database. The c
386d0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
386e0 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ion.** does not 
386f0 68 61 76 65 20 74 6f 20 64 6f 20 61 6e 79 74 68  have to do anyth
38700 69 6e 67 20 73 70 65 63 69 61 6c 20 62 61 73 65  ing special base
38710 64 20 6f 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  d on the value o
38720 66 20 62 50 75 72 67 65 61 62 6c 65 2c 0a 2a 2a  f bPurgeable,.**
38730 20 69 74 20 69 73 20 70 75 72 65 6c 79 20 61 64   it is purely ad
38740 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a 2a 20 54  visory. .**.** T
38750 68 65 20 78 43 61 63 68 65 73 69 7a 65 28 29 20  he xCachesize() 
38760 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 63 61  method may be ca
38770 6c 6c 65 64 20 61 74 20 61 6e 79 20 74 69 6d 65  lled at any time
38780 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 73 65   by SQLite to se
38790 74 20 74 68 65 0a 2a 2a 20 73 75 67 67 65 73 74  t the.** suggest
387a0 65 64 20 6d 61 78 69 6d 75 6d 20 63 61 63 68 65  ed maximum cache
387b0 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66  -size (number of
387c0 20 70 61 67 65 73 20 73 74 6f 72 65 64 20 62 79   pages stored by
387d0 29 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69  ) the cache.** i
387e0 6e 73 74 61 6e 63 65 20 70 61 73 73 65 64 20 61  nstance passed a
387f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first ar