/ Hex Artifact Content
Login

Artifact 96feff9a06728854d010a9d5d297f61b9e1178d9:


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 36 32 20 32 30 30 39 2f 30  n,v 1.462 2009/0
05f0: 38 2f 30 36 20 31 37 3a 34 30 3a 34 36 20 64 72  8/06 17:40:46 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
0e50: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48  nts: [H10011] [H
0e60: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e  10014].*/.#defin
0e70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0e80: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0e90: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0ea0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0eb0: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0ec0: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0ed0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0ee0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0ef0: 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d  Numbers {H10020}
0f00: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59   <S60100>.** KEY
0f10: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
0f20: 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  ersion.**.** The
0f30: 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f 76  se features prov
0f40: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
0f50: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
0f60: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
0f70: 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
0f80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
0f90: 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20  #defines in the 
0fa0: 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 20  header, but are 
0fb0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
0fc0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
0fd0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
0fe0: 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74  ader file.  Caut
0ff0: 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  ious programmers
1000: 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64   might.** includ
1010: 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65  e a check in the
1020: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1030: 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a  o verify that.**
1040: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1050: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77  ion_number() alw
1060: 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1070: 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  value.** [SQLITE
1080: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1090: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10a0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
10b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c0: 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  s the same infor
10d0: 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20  mation as is.** 
10e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
10f0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1100: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66  constant.  The f
1110: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1120: 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69  ded.** for use i
1130: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1140: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1150: 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63  o not have direc
1160: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1170: 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  ng.** constants 
1180: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a  within the DLL..
1190: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
11a0: 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 5b 48 31  ts: [H10021] [H1
11b0: 30 30 32 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a  0022] [H10023].*
11c0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11d0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11e0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
11f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1200: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1210: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1220: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1230: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1240: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1250: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1260: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1270: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1280: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1290: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
12a0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
12b0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
12c0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
12e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
12f0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1300: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1310: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1320: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1330: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1340: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1350: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1360: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1370: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1380: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1390: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13a0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13b0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
13c0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13d0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
13e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
13f0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1400: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1410: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1420: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1430: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1440: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1450: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1460: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1470: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1480: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1490: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14a0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14b0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14c0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14d0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14e0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14f0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1500: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1510: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1520: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1530: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1540: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1550: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1560: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1570: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1580: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1590: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15a0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15b0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
15c0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
15d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
15e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
15f0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1600: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1610: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1620: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1630: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1640: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1650: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1660: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1670: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1680: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1690: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16a0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
16c0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
16d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16e0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1700: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1710: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1720: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1730: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1740: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1750: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1760: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1770: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1780: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1790: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
17a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
17b0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
17c0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
17d0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
17e0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
17f0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1800: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1810: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1820: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1830: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1840: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1850: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1870: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1880: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1890: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
18a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
18b0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
18c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
18d0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
18e0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
18f0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1900: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1910: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1920: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1930: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1940: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1950: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1960: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1980: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1990: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
19a0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
19b0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
19c0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
19d0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
19e0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
19f0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1a00: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a10: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1a20: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1a30: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1a40: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a50: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1a60: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1a70: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1a80: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1a90: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1aa0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ab0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1ac0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ad0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ae0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1af0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1b00: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1b10: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1b20: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1b30: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1b40: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1b50: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1b60: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1b70: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1b80: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1b90: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1ba0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1bd0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1be0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1bf0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1c00: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1c10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1c20: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1c30: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1c40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1c50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
1c60: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
1c70: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
1c80: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1c90: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1ca0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1cb0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1cc0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1cd0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1ce0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1cf0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1d00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1d10: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1d20: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1d30: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1d40: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
1d50: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
1d60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1d70: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
1d80: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1d90: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1da0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1db0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1dc0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1dd0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1de0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1df0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1e00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1e10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1e20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1e30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1e40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
1e50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
1e60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
1e70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
1e80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
1e90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
1ea0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
1eb0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
1ec0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
1ed0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
1ee0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
1ef0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
1f00: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
1f10: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
1f20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1f30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1f40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1f50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1f60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1f70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1f80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1fa0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1fb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1fc0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1fd0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1fe0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ff0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2020: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2030: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2040: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2050: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2070: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2080: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2090: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
20a0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
20c0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
20d0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
20e0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
20f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2100: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2110: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2120: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2130: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2140: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2150: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2160: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2170: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2180: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2190: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
21a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
21b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
21c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
21d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
21e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
21f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2200: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2210: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2230: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2240: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2250: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2260: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2270: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2280: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
22a0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
22b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22c0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
22d0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
22e0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
22f0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
2300: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2310: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2320: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2340: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2350: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2360: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2370: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2380: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2390: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
23a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
23b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
23c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
23d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
23e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
23f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2400: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2410: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2430: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2440: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2450: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2460: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2470: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2480: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2490: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
24a0: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
24b0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24c0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
24d0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
24e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
24f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2530: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2540: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2550: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2560: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2570: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2590: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25a0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
25b0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
25c0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
25d0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
25f0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2600: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2610: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2620: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2630: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2640: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2650: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2660: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2670: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2680: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
26a0: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
26b0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
26c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
26d0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
26e0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
26f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2700: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2710: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2720: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2730: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2740: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2750: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2760: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2770: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2780: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2790: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
27a0: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
27b0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27c0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
27d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
27e0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27f0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2800: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2810: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2820: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2830: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2840: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2850: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2860: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2870: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2880: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
28b0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
28c0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
28d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
28f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2900: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2910: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2920: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2930: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2940: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2950: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2960: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2970: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2980: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2990: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
29a0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
29b0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
29c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29d0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
29e0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
29f0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2a00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2a10: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2a30: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2a40: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2a50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2a60: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2a70: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a80: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2a90: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2aa0: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ab0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2ac0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ae0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2af0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2b20: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2b40: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2b50: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2b60: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2b70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2b80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2b90: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2ba0: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2bb0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2bc0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2bd0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2be0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2bf0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2c00: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
2c10: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
2c20: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
2c30: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
2c40: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
2c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c60: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
2c70: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
2c80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2ca0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2cb0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
2cc0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
2cd0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ce0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
2cf0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
2d00: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
2d10: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d30: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2d40: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2d50: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2d60: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d80: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2d90: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2da0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2db0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
2dc0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
2dd0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2de0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
2df0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
2e00: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
2e10: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
2e20: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
2e30: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2e40: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e50: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
2e60: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
2e70: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
2e80: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
2e90: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
2ea0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
2eb0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
2ec0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
2ed0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
2ee0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
2ef0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f00: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
2f10: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
2f20: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
2f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
2f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
2f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
2f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
2f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
2f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
2f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
2fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
2fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
2fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
2fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
2fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
2ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
3000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
30a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
30b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
30c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
30d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
30e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
30f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
3100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
31a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
31b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
31c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
31d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
31e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
31f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
3200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
32a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
32b0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
32c0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
32d0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
32e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
32f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
3300: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3310: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3320: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3330: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3340: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3350: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3360: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3380: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3390: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
33a0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
33b0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
33d0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
33e0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
33f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3400: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3410: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3420: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3440: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3450: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3460: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3470: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3490: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
34a0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
34b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
34c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34d0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
34e0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
34f0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
3500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3510: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3520: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3530: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3540: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3550: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3560: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3570: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3580: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3590: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
35a0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
35b0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35d0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
35e0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
35f0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
3600: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3610: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3620: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3640: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3650: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3660: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3670: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3680: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3690: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
36a0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
36b0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
36c0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
36d0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
36e0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
36f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3700: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3710: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3720: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3730: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3740: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3750: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3760: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3770: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3780: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3790: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
37a0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37b0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
37c0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
37d0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
37e0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
37f0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3800: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3810: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3820: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3830: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3840: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3850: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3860: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3870: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3880: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3890: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
38a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
38b0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
38c0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
38d0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
38e0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
38f0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3900: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3910: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3920: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3930: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3940: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3950: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3960: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3970: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3980: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3990: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
39a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
39b0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
39c0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
39d0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
39e0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
39f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3a00: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3a10: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3a20: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3a30: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3a40: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3a50: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3a60: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3a70: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3a80: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3a90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3aa0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ab0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3ac0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ad0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ae0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3af0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3b00: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3b10: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3b20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3b30: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3b40: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3b50: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3b60: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3b70: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3b80: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3b90: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3ba0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3bb0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3bc0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3bd0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
3c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
3c30: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
3c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
3c50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3c60: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
3c70: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
3c80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3c90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3ca0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3cb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3cc0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
3cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3ce0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
3cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3d00: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
3d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d20: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
3d30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3d40: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
3d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3d60: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
3d70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3d80: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3da0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3db0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3dc0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
3dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3de0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
3df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3e00: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
3e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e20: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
3e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e40: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
3e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3e60: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
3e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3e80: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ea0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3ec0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3ee0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
3ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f00: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f20: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
3f30: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
3f40: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3f60: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
3f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3f80: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fa0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
3fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3fc0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
3fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3fe0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
3ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4000: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4020: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4030: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4040: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4060: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4070: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4080: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4090: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
40a0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
40b0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
40c0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
40d0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
40e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
40f0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
4100: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4110: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4120: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4130: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4140: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4150: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4160: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4170: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4180: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
4190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
41b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
41c0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
41d0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
41e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
41f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4200: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
4210: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4220: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
4230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4250: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4260: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4270: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
4280: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
42a0: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
42b0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
42c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
42d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
42e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
42f0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4320: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4330: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
4340: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4350: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
4360: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
4370: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
4380: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4390: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
43a0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43b0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
43c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
43d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
43e0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
43f0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
4400: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4410: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4420: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4430: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4460: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4470: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
4480: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4490: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
44a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
44b0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
44c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
44d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
44e0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
44f0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
4500: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
4510: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4520: 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ) */../*.** CAPI
4530: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4540: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4550: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4560: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4570: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4580: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4590: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
45a0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
45b0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
45c0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
45d0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
45e0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
45f0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
4600: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4610: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4620: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4630: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4640: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4650: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4660: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4680: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4690: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
46a0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
46b0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
46c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
46d0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
46e0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
46f0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4700: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4710: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4720: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4730: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4740: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4750: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4760: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4770: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4780: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4790: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
47a0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
47b0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
47c0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
47d0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
47e0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
47f0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4800: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4810: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4820: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4830: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4840: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4850: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4860: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4870: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4880: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4890: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
48a0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
48b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48c0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
48d0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
48e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
48f0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
4900: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4910: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4920: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4930: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4950: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4960: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4980: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4990: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
49a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49b0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
49c0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
49d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
49e0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
49f0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
4a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a10: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
4a20: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4a40: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4a50: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4a70: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4a80: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4aa0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4ab0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4ac0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
4ad0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
4ae0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
4af0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
4b00: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
4b10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4b20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4b30: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4b40: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4b50: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4b60: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4b70: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4b80: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4b90: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4bb0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4bd0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4be0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4c00: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
4c10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
4c20: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
4c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4c40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
4c50: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
4c60: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
4c70: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
4c80: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
4c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
4cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
4ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
4cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
4d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
4d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
4d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
4d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
4d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
4d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
4d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
4d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
4d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
4d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
4da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
4db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
4dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
4dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
4de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
4df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
4e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
4e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
4e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
4e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
4e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
4e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
4e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
4e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
4e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
4e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
4ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
4eb0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
4ec0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4ed0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
4ee0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4ef0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
4f00: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4f20: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
4f30: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
4f40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
4f50: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
4f60: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
4f70: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
4f80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
4f90: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
4fa0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
4fb0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
4fc0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
4fd0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
4fe0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
4ff0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
5000: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
5010: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
5020: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
5030: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
5040: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
5050: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
5060: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
5070: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
5080: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5090: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
50a0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
50b0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
50c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
50d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
50e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
50f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
5100: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
5110: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
5120: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5140: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5150: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5160: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5170: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5180: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5190: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
51a0: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
51b0: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
51c0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
51d0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
51e0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
51f0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
5200: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5210: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
5220: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
5230: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
5240: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
5250: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
5260: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
5270: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
5280: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
5290: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
52a0: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
52b0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
52c0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
52d0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
52e0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
52f0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
5300: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5310: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
5320: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65   xOpen method se
5330: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
5340: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
5350: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
5360: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
5370: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
5380: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
5390: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
53a0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
53b0: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65   if the xOpen re
53c0: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
53d0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
53e0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
53f0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
5400: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
5410: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20  failed xOpen.** 
5420: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e  is for the xOpen
5430: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
5440: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
5450: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c  s element to NUL
5460: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
5470: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
5480: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
5490: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
54a0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
54b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
54c0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
54d0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
54e0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
54f0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
5500: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
5510: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
5520: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
5530: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
5540: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
5550: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
5560: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
5570: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
5580: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
5590: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
55a0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
55b0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
55c0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
55d0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
55e0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
55f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
5600: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
5610: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
5620: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
5630: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5640: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
5650: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5660: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
5670: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5680: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
5690: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
56a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
56b0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
56c0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
56d0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
56e0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
56f0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
5700: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
5710: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
5720: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
5730: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
5740: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
5750: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
5760: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
5770: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
5780: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
5790: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
57a0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
57b0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
57c0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
57d0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
57e0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
57f0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
5800: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
5810: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
5820: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
5830: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
5840: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
5850: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
5860: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
5870: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
5880: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
5890: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
58a0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
58b0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
58c0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
58d0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
58e0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
58f0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
5900: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
5910: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
5920: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
5930: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
5940: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
5950: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
5960: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
5970: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
5980: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
5990: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
59a0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
59b0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
59c0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
59d0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
59e0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
59f0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
5a00: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
5a10: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
5a20: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
5a30: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
5a40: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
5a50: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
5a60: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
5a70: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
5a80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
5a90: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
5aa0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
5ab0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
5ac0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
5ad0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
5ae0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
5af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
5b00: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
5b10: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
5b20: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
5b30: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
5b40: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
5b50: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
5b60: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
5b70: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
5b80: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
5b90: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
5ba0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
5bb0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
5bc0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
5bd0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
5be0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
5bf0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
5c00: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
5c10: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
5c20: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
5c30: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
5c40: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
5c50: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
5c60: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
5c70: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
5c80: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
5c90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ca0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5cb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
5cc0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
5cd0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5ce0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5cf0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5d00: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5d20: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5d30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5d40: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5d50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5d60: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
5d70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d80: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
5d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5da0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
5db0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5dc0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
5dd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
5de0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
5df0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
5e00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5e10: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5e20: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5e30: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5e40: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5e50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e60: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5e70: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5e80: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5e90: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5ea0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5eb0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5ec0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5ed0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5ee0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5ef0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5f10: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5f20: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5f30: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5f40: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5f50: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5f60: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5f70: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5f80: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5f90: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5fa0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5fb0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5fc0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5fd0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5fe0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5ff0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6000: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6010: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6020: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6030: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
6040: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
6050: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
6060: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
6070: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
6080: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
6090: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
60a0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
60b0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
60c0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
60d0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
60e0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
60f0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
6100: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
6110: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
6120: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
6130: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
6140: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
6150: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6160: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
6170: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
6180: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6190: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
61a0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
61b0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
61c0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
61d0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
61e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
61f0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
6200: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
6210: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
6220: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6230: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
6240: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
6250: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
6260: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
6270: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6280: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
6290: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
62a0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
62b0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
62c0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
62d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
62e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
62f0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
6300: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
6310: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
6320: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
6330: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
6340: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
6350: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
6360: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6370: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
6380: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
6390: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
63a0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
63b0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
63c0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
63d0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
63e0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
63f0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
6400: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
6410: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
6420: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
6430: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
6440: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
6450: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
6460: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
6470: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d  Opcodes {H11310}
6480: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
6490: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
64a0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
64b0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
64c0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
64d0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
64e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
64f0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
6500: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
6510: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
6520: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
6530: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
6540: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
6550: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
6560: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
6570: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
6580: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
6590: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
65a0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
65b0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
65c0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
65d0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
65e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
65f0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
6600: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
6610: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6620: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
6630: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
6640: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
6650: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
6660: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
6670: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
6680: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
6690: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
66a0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
66b0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
66c0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
66d0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
66e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
66f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
6700: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
6710: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
6720: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
6730: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6740: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
6750: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
6760: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
6770: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
6780: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6790: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
67a0: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31  e {H17110} <S201
67b0: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  30>.**.** The mu
67c0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
67d0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
67e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
67f0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
6800: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
6810: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
6820: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
6830: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
6840: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
6850: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
6860: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
6870: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
6880: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
6890: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
68a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
68b0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
68c0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
68d0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
68e0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
68f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6900: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
6910: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
6920: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6930: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
6940: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30   {H11140} <S2010
6950: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0>.**.** An inst
6960: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
6970: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
6980: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
6990: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
69a0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
69b0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
69c0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
69d0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
69e0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
69f0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
6a00: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
6a10: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
6a20: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
6a30: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
6a40: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
6a50: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
6a60: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
6a70: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
6a80: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
6a90: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
6aa0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
6ab0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
6ac0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
6ad0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
6ae0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
6af0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
6b00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
6b10: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
6b20: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
6b30: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
6b40: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
6b50: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
6b60: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
6b70: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
6b80: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
6b90: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
6ba0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
6bb0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
6bc0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
6bd0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
6be0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
6bf0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
6c00: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
6c10: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
6c20: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
6c30: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
6c40: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
6c50: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
6c60: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
6c70: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
6c80: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6c90: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
6ca0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
6cb0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
6cc0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
6cd0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
6ce0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
6cf0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
6d00: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
6d10: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
6d20: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
6d30: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
6d40: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
6d50: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
6d60: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
6d70: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
6d80: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
6d90: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
6da0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
6db0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
6dc0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
6dd0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
6de0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
6df0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
6e00: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
6e10: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
6e20: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
6e30: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
6e40: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
6e50: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
6e60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
6e70: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
6e80: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
6e90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
6ea0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
6eb0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
6ec0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
6ed0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
6ee0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
6ef0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
6f00: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
6f10: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
6f20: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
6f30: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
6f40: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75  * SQLite will gu
6f50: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65  arantee that the
6f60: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
6f70: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
6f80: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
6f90: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
6fa0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
6fb0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
6fc0: 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75  me().  SQLite fu
6fd0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
6fe0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
6ff0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
7000: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
7010: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
7020: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
7030: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
7040: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
7050: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
7060: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
7070: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
7080: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
7090: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
70a0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
70b0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
70c0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
70d0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
70e0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
70f0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
7100: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
7110: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
7120: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
7130: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
7140: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
7150: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
7160: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
7170: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
7180: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
7190: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
71a0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
71b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
71c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
71d0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
71e0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
71f0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7200: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7210: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7220: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7230: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7240: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7250: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7260: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7270: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7280: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
7290: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
72a0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
72b0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
72c0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
72d0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
72e0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
72f0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
7300: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
7310: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
7320: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
7330: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
7340: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
7350: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
7360: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
7370: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
7380: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
7390: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
73a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
73b0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
73c0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
73d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
73e0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
73f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7400: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
7410: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7420: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
7430: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7440: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
7450: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7460: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
7470: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
7480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
7490: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
74a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
74b0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
74c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
74d0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
74e0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
74f0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
7500: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
7510: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
7520: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
7530: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
7540: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
7550: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
7560: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
7570: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
7580: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
7590: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
75a0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
75b0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
75c0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
75d0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
75e0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
75f0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
7600: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
7610: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
7620: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
7630: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
7640: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
7650: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
7660: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
7670: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
7680: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
7690: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
76a0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
76b0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
76c0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
76d0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
76e0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
76f0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
7700: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
7710: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
7720: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
7730: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7740: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7750: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
7760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7770: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
7780: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7790: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
77a0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
77b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
77c0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
77d0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
77e0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50    The [SQLITE_OP
77f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7800: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
7810: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62   for TEMP  datab
7820: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61  ases, journals a
7830: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61  nd for subjourna
7840: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ls..**.** The [S
7850: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7860: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
7870: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
7880: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
7890: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
78a0: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
78b0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
78c0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
78d0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
78e0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
78f0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
7900: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
7910: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
7920: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
7930: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
7940: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
7950: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
7960: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
7970: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
7980: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
7990: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
79a0: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
79b0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
79c0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
79d0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
79e0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
79f0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7a00: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
7a10: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
7a20: 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20  .**.** At least 
7a30: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
7a40: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
7a50: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
7a60: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
7a70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7a80: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
7a90: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
7aa0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
7ab0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
7ac0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
7ad0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
7ae0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
7af0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
7b00: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
7b10: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
7b20: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
7b30: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7b40: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
7b50: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
7b60: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
7b70: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7b80: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
7b90: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
7ba0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
7bb0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
7bc0: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
7bd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7be0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
7bf0: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
7c00: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
7c10: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
7c20: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
7c30: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
7c40: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
7c50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7c60: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
7c70: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
7c80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
7c90: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
7ca0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
7cb0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
7cc0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
7cd0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
7ce0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
7cf0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
7d00: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
7d10: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
7d20: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
7d30: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
7d40: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
7d50: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
7d60: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
7d70: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53  rectory..**.** S
7d80: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
7d90: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
7da0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
7db0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
7dc0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
7dd0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
7de0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
7df0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
7e00: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
7e10: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
7e20: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
7e30: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
7e40: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
7e50: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
7e60: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
7e70: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
7e80: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
7e90: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
7ea0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
7eb0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
7ec0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
7ed0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
7ee0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
7ef0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
7f00: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
7f10: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
7f20: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
7f30: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
7f40: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e  (), xSleep(), an
7f50: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  d xCurrentTime()
7f60: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
7f70: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
7f80: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
7f90: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
7fa0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
7fb0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
7fc0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
7fd0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
7fe0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
7ff0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
8000: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
8010: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
8020: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
8030: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
8040: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
8050: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
8060: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
8070: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
8080: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
8090: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
80a0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
80b0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
80c0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
80d0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
80e0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
80f0: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75   given.  The xCu
8100: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
8110: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8120: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
8130: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
8140: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e  t date and time.
8150: 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  .**.*/.typedef s
8160: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8170: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
8180: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8190: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
81a0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
81b0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
81c0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
81d0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
81e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
81f0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
8200: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
8210: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8220: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
8230: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
8240: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
8250: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
8260: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
8270: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
8280: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
8290: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
82a0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
82b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
82c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
82d0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
82e0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
82f0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
8300: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
8310: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8320: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8330: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
8340: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
8350: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
8360: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
8370: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
8380: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
8390: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
83a0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
83b0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
83c0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
83d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
83e0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
83f0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
8400: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
8410: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
8420: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8430: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
8440: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8450: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
8460: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8470: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
8480: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
8490: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
84a0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
84b0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
84c0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
84d0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
84e0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
84f0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
8500: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
8510: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
8520: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
8530: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
8540: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
8550: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
8560: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
8570: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
8580: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
8590: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
85a0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
85b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
85c0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
85d0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
85e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
85f0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
8600: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  /* New fields ma
8610: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
8620: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
8630: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
8640: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
8650: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
8660: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
8670: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8680: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
8690: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
86a0: 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30  S method {H11190
86b0: 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a  } <H11140>.**.**
86c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
86d0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
86e0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
86f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
8700: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
8710: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
8720: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
8730: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74   {END}  They det
8740: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
8750: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
8760: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
8770: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
8780: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
8790: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
87a0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
87b0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
87c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
87d0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
87e0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
87f0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8800: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
8810: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
8820: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
8830: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
8840: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a   and writable..*
8850: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
8860: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
8870: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
8880: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
8890: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
88a0: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
88b0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
88c0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
88d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
88e0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
88f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8900: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
8910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8920: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
8930: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
8940: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c  10130} <S20000><
8950: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
8960: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8970: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
8980: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
8990: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
89a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
89b0: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
89c0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
89d0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
89e0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
89f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
8a00: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  itialize()..**.*
8a10: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
8a20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8a30: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
8a40: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
8a50: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
8a60: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
8a70: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
8a80: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
8a90: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
8aa0: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
8ab0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
8ac0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
8ad0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
8ae0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
8af0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
8b00: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
8b10: 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69   Only an effecti
8b20: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
8b30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8b40: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
8b50: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
8b60: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
8b70: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
8b80: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ops..**.** A cal
8b90: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
8ba0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
8bb0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
8bc0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
8bd0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
8be0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
8bf0: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
8c00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8c10: 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 6e  e().  Only.** an
8c20: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
8c30: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
8c40: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
8c50: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
8c60: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  .** All other ca
8c70: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
8c80: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
8c90: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
8ca0: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
8cb0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
8cc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
8cd0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
8ce0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
8cf0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
8d00: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
8d10: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
8d20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
8d30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
8d40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8d50: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8d60: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
8d70: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66  success..** If f
8d80: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
8d90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8da0: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
8db0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
8dc0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
8dd0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
8de0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
8df0: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
8e00: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
8e10: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
8e20: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
8e30: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
8e40: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  E_OK]..**.** The
8e50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8e60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
8e70: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
8e80: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
8e90: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
8ea0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
8eb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
8ec0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
8ed0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
8ee0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8ef0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
8f00: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
8f10: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
8f20: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
8f30: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
8f40: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
8f50: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
8f60: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
8f70: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
8f80: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
8f90: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
8fa0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
8fb0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
8fc0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
8fd0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
8fe0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
8ff0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
9000: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
9010: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
9020: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
9030: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
9040: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
9050: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
9060: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
9070: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
9080: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9090: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
90a0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
90b0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
90c0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
90d0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
90e0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
90f0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
9100: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
9110: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9120: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
9130: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
9140: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9150: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
9160: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
9170: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
9180: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
9190: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
91a0: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
91b0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
91c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
91d0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
91e0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
91f0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
9200: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
9210: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
9220: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
9230: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
9240: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
9250: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
9260: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
9270: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
9280: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
9290: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
92a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
92b0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
92c0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
92d0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
92e0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
92f0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
9300: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
9310: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
9320: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
9330: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
9340: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
9350: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9360: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
9370: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
9380: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
9390: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
93a0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
93b0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
93c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
93d0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
93e0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
93f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
9400: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
9410: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
9420: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
9430: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
9440: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
9450: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9460: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
9470: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9480: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
9490: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
94a0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
94b0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
94c0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
94d0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
94e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
94f0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
9500: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
9510: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
9520: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
9530: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
9540: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
9550: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9560: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
9570: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
9580: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
9590: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
95a0: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
95b0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
95c0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
95d0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
95e0: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
95f0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
9600: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
9610: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
9620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
9630: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
9640: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
9650: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
9660: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
9670: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
9680: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
9690: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
96a0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
96b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
96c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
96d0: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
96e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
96f0: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
9700: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
9710: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
9720: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
9730: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
9740: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9750: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
9760: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9770: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
9780: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
9790: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
97a0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
97b0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
97c0: 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c  brary {H14100} <
97d0: 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a  S20000><S30200>.
97e0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
97f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9800: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
9810: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
9820: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
9830: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
9840: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
9850: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
9860: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
9870: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
9880: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
9890: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
98a0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
98b0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
98c0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
98d0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
98e0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
98f0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
9900: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
9910: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
9920: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
9930: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
9940: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
9950: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9960: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9970: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
9980: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
9990: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
99a0: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
99b0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
99c0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
99d0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
99e0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
99f0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
9a00: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
9a10: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
9a20: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
9a30: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
9a40: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
9a50: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
9a60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
9a70: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
9a80: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
9a90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9aa0: 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  ()]..** Note, ho
9ab0: 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69  wever, that sqli
9ac0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
9ad0: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
9ae0: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
9af0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
9b00: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
9b10: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
9b20: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
9b30: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
9b40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
9b50: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
9b60: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
9b70: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
9b80: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
9b90: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
9ba0: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
9bb0: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
9bc0: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
9bd0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
9be0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
9bf0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
9c00: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
9c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
9c20: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
9c30: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
9c40: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
9c50: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
9c60: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
9c70: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
9c80: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
9c90: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
9ca0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20  LITE_OK]..** If 
9cb0: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
9cc0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
9cd0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
9ce0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
9cf0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
9d00: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
9d10: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
9d20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
9d30: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33  ents:.** [H14103
9d40: 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31  ] [H14106] [H141
9d50: 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31  20] [H14123] [H1
9d60: 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b  4126] [H14129] [
9d70: 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d  H14132] [H14135]
9d80: 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31  .** [H14138] [H1
9d90: 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b  4141] [H14144] [
9da0: 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d  H14147] [H14150]
9db0: 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35   [H14153] [H1415
9dc0: 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b  6] [H14159].** [
9dd0: 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d  H14162] [H14165]
9de0: 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c   [H14168].*/.SQL
9df0: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
9e00: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
9e10: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
9e20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9e30: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
9e40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20  se connections  
9e50: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30  {H14200} <S20000
9e60: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
9e70: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
9e80: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
9e90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
9ea0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
9eb0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
9ec0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
9ed0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
9ee0: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
9ef0: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
9f00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9f10: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
9f20: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
9f30: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
9f40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9f50: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
9f60: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
9f70: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20  ument).  The.** 
9f80: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
9f90: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
9fa0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  n only be used i
9fb0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
9fc0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
9fd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
9fe0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
9ff0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
a000: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
a010: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
a020: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
a030: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
a040: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
a050: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
a060: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
a070: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
a080: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
a090: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
a0a0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
a0b0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
a0c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a0d0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
a0e0: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
a0f0: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
a100: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
a110: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
a120: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
a130: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
a140: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
a150: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
a170: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
a180: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
a190: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65  e verb..**.** Re
a1a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
a1b0: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d  H14203] [H14206]
a1c0: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31   [H14209] [H1421
a1d0: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53  2] [H14215].*/.S
a1e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
a1f0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
a200: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
a210: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
a220: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a230: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
a240: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
a250: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
a260: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
a270: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a280: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a290: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a2a0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a2b0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a2c0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a2d0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a2e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
a2f0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
a300: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
a310: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
a320: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
a330: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
a340: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a350: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a360: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
a370: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
a380: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a390: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a3b0: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
a3c0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
a3d0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
a3e0: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
a3f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
a400: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
a410: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
a420: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
a430: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
a440: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
a450: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
a460: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
a470: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
a480: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
a490: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
a4a0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
a4b0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
a4c0: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
a4d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
a4e0: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
a4f0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
a500: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
a510: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
a520: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
a530: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
a540: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
a550: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
a560: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
a570: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
a580: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
a590: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
a5a0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
a5b0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
a5c0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
a5d0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
a5e0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
a5f0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
a600: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
a610: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
a620: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
a630: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
a640: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
a650: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
a660: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
a670: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
a680: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
a690: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
a6a0: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
a6b0: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
a6c0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
a6d0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
a6e0: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
a6f0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
a700: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
a710: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
a720: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
a730: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
a740: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
a750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a760: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
a770: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
a780: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
a790: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
a7a0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
a7b0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
a7c0: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
a7d0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
a7e0: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
a7f0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
a800: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
a810: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
a820: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a830: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
a840: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
a850: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
a860: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
a870: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
a880: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a890: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a8a0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
a8b0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
a8c0: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
a8d0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
a8e0: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
a8f0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
a900: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
a910: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
a920: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
a930: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
a940: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
a950: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
a960: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
a970: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
a980: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
a990: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
a9a0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
a9b0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
a9c0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
a9d0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
a9e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
a9f0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
aa00: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
aa10: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
aa20: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
aa30: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
aa40: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
aa50: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
aa60: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
aa70: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
aa80: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
aa90: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
aaa0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
aab0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
aac0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
aad0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
aae0: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
aaf0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
ab00: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
ab10: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
ab20: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
ab30: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
ab40: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
ab50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
ab60: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
ab70: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
ab80: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
ab90: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
aba0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
abb0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
abc0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
abd0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
abe0: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
abf0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
ac00: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
ac10: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
ac20: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
ac30: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
ac40: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
ac50: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
ac60: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
ac70: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
ac80: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
ac90: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
aca0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
acb0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
acc0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
acd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
ace0: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
acf0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
ad00: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
ad10: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
ad20: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
ad30: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
ad40: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
ad50: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
ad60: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
ad70: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
ad80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ad90: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
ada0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
adb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
adc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
add0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ade0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
adf0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ae00: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
ae10: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
ae20: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
ae30: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
ae40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ae50: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
ae60: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
ae70: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
ae80: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
ae90: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
aea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
aeb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
aec0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
aed0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
aee0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
aef0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
af00: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
af10: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
af20: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
af30: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
af40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
af50: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
af60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
af70: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
af80: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
af90: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
afa0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
afb0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
afc0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
afd0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
afe0: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
aff0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
b000: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
b010: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
b020: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
b030: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
b040: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b050: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
b060: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
b070: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
b080: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
b090: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
b0a0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
b0b0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
b0c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b0d0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b0e0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b0f0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
b100: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
b110: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
b120: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
b130: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b140: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
b150: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
b160: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
b170: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
b180: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
b190: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
b1a0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
b1b0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
b1c0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
b1d0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
b1e0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
b1f0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
b200: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b210: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
b220: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
b230: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
b240: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
b250: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
b260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
b270: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b280: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
b290: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
b2a0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
b2b0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
b2c0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
b2d0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
b2e0: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
b2f0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
b300: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
b310: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
b320: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
b330: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
b340: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
b350: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
b360: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
b370: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
b380: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
b390: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
b3a0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
b3b0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
b3c0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
b3d0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
b3e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b3f0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
b400: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
b410: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
b420: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
b430: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
b440: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b450: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
b460: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
b470: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
b480: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
b490: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
b4a0: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
b4b0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
b4c0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
b4d0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
b4e0: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
b4f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b500: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
b510: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b520: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
b530: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
b540: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
b550: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
b560: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
b570: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
b580: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
b590: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
b5a0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
b5b0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
b5c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
b5d0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
b5e0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
b5f0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b600: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
b610: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
b620: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b630: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
b640: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
b650: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b660: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
b670: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
b680: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b690: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
b6a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
b6b0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
b6c0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
b6d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
b6e0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
b6f0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
b700: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
b710: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
b720: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
b730: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
b740: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
b750: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
b760: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b770: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
b780: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
b790: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
b7a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b7b0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
b7c0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
b7d0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
b7e0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b7f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
b800: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
b810: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b820: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
b830: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
b840: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
b850: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
b860: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
b870: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
b880: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
b890: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
b8a0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
b8b0: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
b8c0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
b8d0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
b8e0: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
b8f0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
b900: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
b910: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
b920: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
b930: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
b940: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
b950: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b960: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
b970: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
b980: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
b990: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
b9a0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b9b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
b9c0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
b9d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
b9e0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
b9f0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
ba00: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
ba10: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
ba20: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
ba30: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
ba40: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
ba50: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
ba60: 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
ba70: 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
ba80: 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69   scrach allocati
ba90: 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
baa0: 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
bab0: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
bac0: 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
bad0: 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
bae0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
baf0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
bb00: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
bb10: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
bb20: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
bb30: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
bb40: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
bb50: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
bb60: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
bb70: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
bb80: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
bb90: 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72  to internal over
bba0: 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  head..** The fir
bbb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
bbc0: 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
bbd0: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
bbe0: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
bbf0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
bc00: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
bc10: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
bc20: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
bc30: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
bc40: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
bc50: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
bc60: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
bc70: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
bc80: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
bc90: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
bca0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
bcb0: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
bcc0: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
bcd0: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
bce0: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
bcf0: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
bd00: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
bd10: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
bd20: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
bd30: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
bd40: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
bd50: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
bd60: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bd70: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
bd80: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
bd90: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
bda0: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
bdb0: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
bdc0: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
bdd0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
bde0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
bdf0: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
be00: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
be10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
be20: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
be30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
be40: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
be50: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
be60: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
be70: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
be80: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
be90: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
bea0: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
beb0: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
bec0: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
bed0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
bee0: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
bef0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
bf00: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
bf10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
bf20: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
bf30: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
bf40: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
bf50: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
bf60: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
bf70: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
bf80: 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
bf90: 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
bfa0: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
bfb0: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
bfc0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
bfd0: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
bfe0: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
bff0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
c000: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c010: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
c020: 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
c030: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
c040: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
c050: 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
c060: 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
c070: 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 54   page header.  T
c080: 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
c090: 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
c0a0: 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
c0b0: 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
c0c0: 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 49 74  rchitecture.  It
c0d0: 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
c0e0: 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
c0f0: 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
c100: 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
c110: 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
c120: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
c130: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
c140: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
c150: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
c160: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
c170: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
c180: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
c190: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
c1a0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c1b0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
c1c0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
c1d0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
c1e0: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
c1f0: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49  dds to cache.  I
c200: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
c210: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
c220: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
c230: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
c240: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
c250: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
c260: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
c270: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
c280: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
c290: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
c2a0: 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
c2b0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
c2c0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
c2d0: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
c2e0: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
c2f0: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
c300: 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e  mation. The poin
c310: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
c320: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
c330: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
c340: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
c350: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
c360: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
c370: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
c380: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
c390: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c3a0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
c3b0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c3c0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
c3d0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
c3e0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
c3f0: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
c400: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
c410: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
c420: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
c430: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
c440: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
c450: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
c460: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
c470: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c480: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
c490: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c4a0: 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
c4b0: 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
c4c0: 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
c4d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
c4e0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
c4f0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
c500: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
c510: 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49 66 20 74 68  n size..** If th
c520: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
c530: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
c540: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
c550: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
c560: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
c570: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
c580: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
c590: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
c5a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
c5b0: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
c5c0: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
c5d0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
c5e0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20  IG_MALLOC].  If 
c5f0: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
c600: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
c610: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
c620: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
c630: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
c640: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
c650: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
c660: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
c670: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
c680: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
c690: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
c6a0: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
c6b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
c6c0: 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
c6d0: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
c6e0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
c6f0: 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
c700: 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
c710: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
c720: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
c730: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
c740: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
c750: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c760: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
c770: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c780: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
c790: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c7a0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
c7b0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c7c0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c7d0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c7e0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c7f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
c800: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
c810: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
c820: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
c830: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
c840: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
c850: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
c860: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
c870: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c880: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
c890: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
c8a0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c8b0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c8c0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c8d0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c8e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c8f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c900: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c910: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
c920: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
c930: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
c940: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c950: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
c960: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
c970: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
c980: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
c990: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
c9a0: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
c9b0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c9c0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c9d0: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
c9e0: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
c9f0: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
ca00: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
ca10: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
ca20: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ca30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
ca40: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
ca50: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
ca60: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
ca70: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
ca80: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
ca90: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74  ** memory allcat
caa0: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70  ion lookaside op
cab0: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65  timization.  The
cac0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
cad0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
cae0: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
caf0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
cb00: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
cb10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
cb20: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
cb30: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
cb40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64   connection.</dd
cb50: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
cb60: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
cb70: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
cb80: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
cb90: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
cba0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
cbb0: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
cbc0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
cbd0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
cbe0: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
cbf0: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
cc00: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
cc10: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
cc20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51  lementation.  SQ
cc30: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
cc40: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
cc50: 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
cc60: 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
cc70: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
cc80: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cc90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
cca0: 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  ETPCACHE</dt>.**
ccb0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
ccc0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ccd0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
cce0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ccf0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
cd00: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
cd10: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
cd20: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
cd30: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
cd40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
cd50: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
cd60: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  t.</dd>.**.** </
cd70: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
cd80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
cd90: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
cda0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
cdb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
cdc0: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
cdd0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
cde0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
cdf0: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
ce00: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
ce10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ce20: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
ce30: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
ce40: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
ce50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ce60: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
ce70: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
ce80: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
ce90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cea0: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
ceb0: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
cec0: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
ced0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cee0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
cef0: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
cf00: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
cf10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cf20: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
cf30: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
cf40: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
cf50: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
cf60: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
cf70: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
cf80: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
cf90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cfa0: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
cfb0: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
cfc0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
cfd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cfe0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
cff0: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
d000: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d010: 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
d020: 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
d030: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
d040: 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
d050: 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
d060: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
d070: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
d080: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
d090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d0a0: 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
d0b0: 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
d0c0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
d0d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d0e0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
d0f0: 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
d100: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
d110: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ods* */../*.** C
d120: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
d130: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
d140: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e  H10170} <S20000>
d150: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
d160: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
d170: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
d180: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
d190: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d1a0: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
d1b0: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
d1c0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
d1d0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
d1e0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
d1f0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
d200: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
d210: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
d220: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
d230: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
d240: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
d250: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
d260: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
d270: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
d280: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
d290: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
d2a0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
d2b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
d2c0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
d2d0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
d2e0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
d2f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
d300: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
d310: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
d320: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
d330: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
d340: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
d350: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
d360: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d370: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
d380: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
d390: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
d3a0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
d3b0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
d3c0: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
d3d0: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
d3e0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
d3f0: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
d400: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
d410: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
d420: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
d430: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d440: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
d450: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
d460: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
d470: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
d480: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
d490: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
d4a0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
d4b0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
d4c0: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
d4d0: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65  e memory..** The
d4e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
d4f0: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
d500: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
d510: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
d520: 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
d530: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
d540: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
d550: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
d560: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
d570: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
d580: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
d590: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
d5a0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
d5b0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d5c0: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
d5d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
d5e0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
d5f0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
d600: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
d610: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
d620: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
d630: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
d640: 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64  d arguments.</dd
d650: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
d660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d670: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
d680: 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76  DE    1001  /* v
d690: 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
d6a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d6b0: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
d6c0: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
d6d0: 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30  ult Codes {H1220
d6e0: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
d6f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
d700: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
d710: 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
d720: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
d730: 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
d740: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
d750: 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
d760: 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  te. The extended
d770: 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
d780: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
d790: 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
d7a0: 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
d7b0: 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74  ility considerat
d7c0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ions..**.** Requ
d7d0: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
d7e0: 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d 0a 2a  2201] [H12202].*
d7f0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
d800: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
d810: 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
d820: 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
d830: 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
d840: 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31  Insert Rowid {H1
d850: 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  2220} <S10700>.*
d860: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
d870: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
d880: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
d890: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
d8a0: 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
d8b0: 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
d8c0: 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72   "rowid"]. The r
d8d0: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
d8e0: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
d8f0: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
d900: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
d910: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
d920: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
d930: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
d940: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
d950: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
d960: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
d970: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
d980: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
d990: 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
d9a0: 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
d9b0: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
d9c0: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
d9d0: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
d9e0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
d9f0: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
da00: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
da10: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
da20: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
da30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
da40: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
da50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
da60: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
da70: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73  gument.  If no s
da80: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
da90: 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
daa0: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
dab0: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
dac0: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
dad0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
dae0: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
daf0: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
db00: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
db10: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
db20: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
db30: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
db40: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
db50: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
db60: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
db70: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
db80: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
db90: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
dba0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
dbb0: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
dbc0: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
dbd0: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
dbe0: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
dbf0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49  red..**.** An [I
dc00: 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
dc10: 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
dc20: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
dc30: 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
dc40: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
dc50: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
dc60: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
dc70: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
dc80: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
dc90: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
dca0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
dcb0: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
dcc0: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
dcd0: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
dce0: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
dcf0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
dd00: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
dd10: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
dd20: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
dd30: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
dd40: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
dd50: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
dd60: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
dd70: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
dd80: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
dd90: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
dda0: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
ddb0: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
ddc0: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
ddd0: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
dde0: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
ddf0: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
de00: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
de10: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
de20: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
de30: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
de40: 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
de50: 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
de60: 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
de70: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
de80: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
de90: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
dea0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
deb0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
dec0: 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b  s:.** [H12221] [
ded0: 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12223].**.** If
dee0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
def0: 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
df00: 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
df10: 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
df20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
df30: 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
df40: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
df50: 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
df60: 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
df70: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
df80: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
df90: 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
dfa0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
dfb0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
dfc0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
dfd0: 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
dfe0: 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
dff0: 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
e000: 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
e010: 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
e020: 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
e030: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
e040: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
e050: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
e060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e070: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
e080: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
e090: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c  ified {H12240} <
e0a0: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10600>.**.** Th
e0b0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
e0c0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
e0d0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
e0e0: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
e0f0: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
e100: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
e110: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
e120: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
e130: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
e140: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
e150: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
e160: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
e170: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e  parameter..** On
e180: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
e190: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
e1a0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
e1b0: 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
e1c0: 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
e1d0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
e1e0: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
e1f0: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
e200: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
e210: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
e220: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
e230: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e240: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
e250: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
e260: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
e270: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
e280: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e290: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
e2a0: 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
e2b0: 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
e2c0: 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
e2d0: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
e2e0: 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
e2f0: 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
e300: 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
e310: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
e320: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
e330: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
e340: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
e350: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
e360: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
e370: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
e380: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
e390: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
e3a0: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
e3b0: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
e3c0: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
e3d0: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
e3e0: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
e3f0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
e400: 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
e410: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
e420: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
e430: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
e440: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  t row changes..*
e450: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
e460: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
e470: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
e480: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
e490: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
e4a0: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
e4b0: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
e4c0: 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
e4d0: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
e4e0: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
e4f0: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
e500: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
e510: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
e520: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
e530: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
e540: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
e550: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
e560: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
e570: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
e580: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
e590: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
e5a0: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
e5b0: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
e5c0: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
e5d0: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
e5e0: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b  .**.** Calling [
e5f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
e600: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
e610: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
e620: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
e630: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
e640: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
e650: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
e660: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
e670: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
e680: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
e690: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e6a0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e6b0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e6c0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
e6d0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
e6e0: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c  ext..**.** Thus,
e6f0: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
e700: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
e710: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
e720: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
e730: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
e740: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
e750: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
e760: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
e770: 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
e780: 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
e790: 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65  vel.  Within the
e7a0: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
e7b0: 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
e7c0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
e7d0: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
e7e0: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
e7f0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
e800: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
e810: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
e820: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
e830: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
e840: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
e850: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
e860: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
e870: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
e880: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
e890: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
e8a0: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
e8b0: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
e8c0: 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
e8d0: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
e8e0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ntext..**.** See
e8f0: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
e900: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e910: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
e920: 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  d the.** [count_
e930: 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e  changes pragma].
e940: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
e950: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d  nts:.** [H12241]
e960: 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20   [H12243].**.** 
e970: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
e980: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
e990: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
e9a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9b0: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
e9c0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
e9d0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
e9e0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
e9f0: 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
ea00: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
ea10: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
ea20: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
ea30: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
ea40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
ea50: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
ea60: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
ea70: 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  260} <S10600>.**
ea80: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
ea90: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
eaa0: 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
eab0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
eac0: 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
ead0: 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
eae0: 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
eaf0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
eb00: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
eb10: 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f  pened..** The co
eb20: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
eb30: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
eb40: 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20 54 52  l .** [CREATE TR
eb50: 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
eb60: 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
eb70: 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
eb80: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
eb90: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
eba0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
ebb0: 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
ebc0: 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
ebd0: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
ebe0: 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
ebf0: 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
ec00: 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
ec10: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
ec20: 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
ec30: 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
ec40: 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
ec50: 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
ec60: 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
ec70: 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
ec80: 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
ec90: 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
eca0: 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
ecb0: 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73  ..** The changes
ecc0: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
ecd0: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74  soon as the stat
ece0: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
ecf0: 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70   them is.** comp
ed00: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
ed10: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
ed20: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
ed30: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
ed40: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
ed50: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
ed60: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
ed70: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
ed80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
ed90: 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  d the.** [count_
eda0: 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e  changes pragma].
edb0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
edc0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d  nts:.** [H12261]
edd0: 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20   [H12263].**.** 
ede0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
edf0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
ee00: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
ee10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ee20: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
ee30: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
ee40: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
ee50: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
ee60: 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
ee70: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
ee80: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
ee90: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
eea0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
eeb0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
eec0: 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
eed0: 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
eee0: 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30  ng Query {H12270
eef0: 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30500>.**.**
ef00: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63   This function c
ef10: 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
ef20: 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
ef30: 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
ef40: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
ef50: 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
ef60: 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
ef70: 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
ef80: 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
ef90: 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
efa0: 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
efb0: 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
efc0: 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
efd0: 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
efe0: 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
eff0: 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
f000: 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
f010: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ely..**.** It is
f020: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
f030: 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
f040: 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
f050: 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
f060: 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
f070: 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
f080: 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
f090: 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
f0a0: 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
f0b0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
f0c0: 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
f0d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f0e0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
f0f0: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
f100: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
f110: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
f120: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  urns..**.** If a
f130: 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
f140: 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
f150: 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
f160: 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
f170: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
f180: 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
f190: 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
f1a0: 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
f1b0: 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
f1c0: 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
f1d0: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
f1e0: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e  letion..**.** An
f1f0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
f200: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
f210: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
f220: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
f230: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
f240: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
f250: 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
f260: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
f270: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
f280: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
f290: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
f2a0: 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
f2b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
f2c0: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
f2d0: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
f2e0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
f2f0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
f300: 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
f310: 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
f320: 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
f330: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
f340: 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
f350: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
f360: 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77  mplete.  Any new
f370: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
f380: 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
f390: 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
f3a0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
f3b0: 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
f3c0: 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
f3d0: 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
f3e0: 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
f3f0: 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
f400: 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
f410: 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
f420: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
f430: 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
f440: 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   New SQL stateme
f450: 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
f460: 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
f470: 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
f480: 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
f490: 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
f4a0: 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
f4b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
f4c0: 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c  upt()..** A call
f4d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
f4e0: 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
f4f0: 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
f500: 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
f510: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
f520: 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
f530: 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
f540: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
f550: 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
f560: 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
f570: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
f580: 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
f590: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
f5a0: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20  ts:.** [H12271] 
f5b0: 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49  [H12272].**.** I
f5c0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
f5d0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
f5e0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
f5f0: 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
f600: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
f610: 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
f620: 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
f630: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
f640: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
f650: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
f660: 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
f670: 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
f680: 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b  nt Is Complete {
f690: 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e  H10510} <S70200>
f6a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f6b0: 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
f6c0: 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
f6d0: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
f6e0: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
f6f0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
f700: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
f710: 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
f720: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
f730: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
f740: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
f750: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
f760: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
f770: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
f780: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
f790: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
f7a0: 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
f7b0: 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
f7c0: 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
f7d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
f7e0: 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20   A statement is 
f7f0: 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
f800: 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
f810: 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
f820: 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
f830: 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
f840: 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
f850: 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
f860: 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
f870: 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
f880: 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
f890: 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
f8a0: 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
f8b0: 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
f8c0: 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
f8d0: 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
f8e0: 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
f8f0: 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
f900: 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
f910: 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
f920: 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
f930: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
f940: 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
f950: 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63  ator.  Whitespac
f960: 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
f970: 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
f980: 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
f990: 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
f9a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
f9b0: 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
f9c0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
f9d0: 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66   incomplete.  If
f9e0: 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
f9f0: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
fa00: 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
fa10: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
fa20: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
fa30: 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
fa40: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
fa50: 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
fa60: 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
fa70: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
fa80: 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66  ct SQL..**.** If
fa90: 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
faa0: 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
fab0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
fac0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
fad0: 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
fae0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
faf0: 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
fb00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fb10: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fb20: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
fb30: 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
fb40: 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
fb50: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fb60: 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
fb70: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
fb80: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
fb90: 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
fba0: 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
fbb0: 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
fbc0: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
fbd0: 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
fbe0: 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  lete..**.** Requ
fbf0: 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31  irements: [H1051
fc00: 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a  1] [H10512].**.*
fc10: 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
fc20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fc30: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
fc40: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
fc50: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
fc60: 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
fc70: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
fc80: 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
fc90: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
fca0: 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
fcb0: 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
fcc0: 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
fcd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
fce0: 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
fcf0: 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
fd00: 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
fd10: 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
fd20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
fd30: 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
fd40: 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
fd50: 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b  TE_BUSY Errors {
fd60: 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e  H12310} <S40400>
fd70: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
fd80: 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
fd90: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
fda0: 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
fdb0: 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
fdc0: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
fdd0: 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
fde0: 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
fdf0: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
fe00: 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
fe10: 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49   locked..**.** I
fe20: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
fe30: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
fe40: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
fe50: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
fe60: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
fe70: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
fe80: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
fe90: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
fea0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
feb0: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
fec0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
fed0: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20  allback will be 
fee0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
fef0: 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
ff00: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
ff10: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
ff20: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
ff30: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
ff40: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
ff50: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
ff60: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
ff70: 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68  y_handler().  Th
ff80: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
ff90: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
ffa0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
ffb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
ffc0: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
ffd0: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
ffe0: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
fff0: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
10000 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a  vent.  If the.**
10010 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
10020 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
10030 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
10040 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
10050 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
10060 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
10070 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
10080 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10090 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
100a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
100b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
100c0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
100d0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
100e0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
100f0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
10100 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
10110 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
10120 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
10130 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
10140 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
10150 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
10160 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
10170 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
10180 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
10190 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
101a0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
101b0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
101c0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
101d0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
101e0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
101f0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
10200 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
10210 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10220 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
10230 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
10240 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10250 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
10260 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
10270 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
10280 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
10290 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
102a0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
102b0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
102c0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
102d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
102e0 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
102f0 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
10300 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
10310 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
10320 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
10330 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
10340 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
10350 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
10360 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
10370 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
10380 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
10390 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
103a0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
103b0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
103c0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
103d0 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
103e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
103f0 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
10400 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
10410 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
10420 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
10430 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
10440 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
10450 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
10460 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
10470 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
10480 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
10490 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
104a0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
104b0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
104c0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
104d0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
104e0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
104f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
10500 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
10510 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
10520 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
10530 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
10540 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
10550 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
10560 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
10570 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
10580 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
10590 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
105a0 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
105b0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
105c0 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
105d0 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
105e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
105f0 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
10600 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
10610 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
10620 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
10630 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
10640 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
10650 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
10660 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
10670 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
10680 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
10690 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
106a0 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
106b0 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
106c0 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
106d0 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
106e0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
106f0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
10700 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
10710 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
10720 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
10730 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
10740 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
10750 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
10760 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
10770 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
10780 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
10790 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
107a0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
107b0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
107c0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
107d0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
107e0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
107f0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
10800 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
10810 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
10820 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
10830 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
10840 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
10850 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ortant..**.** Th
10860 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
10870 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
10880 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
10890 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
108a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
108b0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
108c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
108d0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
108e0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
108f0 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61  r.  Note that ca
10900 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
10910 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
10920 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
10930 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
10940 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
10950 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
10960 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
10970 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
10980 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
10990 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
109a0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
109b0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
109c0 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
109d0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
109e0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
109f0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
10a00 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
10a10 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31   [H12311] [H1231
10a20 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32  2] [H12314] [H12
10a30 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a  316] [H12318].**
10a40 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
10a50 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
10a60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
10a70 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
10a80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10a90 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
10aa0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
10ab0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
10ac0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10ad0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
10ae0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
10af0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
10b00 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
10b10 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30   Timeout {H12340
10b20 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a  } <S40410>.**.**
10b30 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
10b40 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
10b50 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
10b60 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
10b70 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
10b80 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
10b90 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
10ba0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
10bb0 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a    The handler.**
10bc0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
10bd0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
10be0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
10bf0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
10c00 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
10c10 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31  accumulated. {H1
10c20 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22  2343} After "ms"
10c30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
10c40 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
10c50 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
10c60 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
10c70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10c80 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
10c90 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10ca0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10cb0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
10cc0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
10cd0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
10ce0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
10cf0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
10d00 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
10d10 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
10d20 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
10d30 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
10d40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
10d50 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
10d60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10d70 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
10d80 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
10d90 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
10da0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
10db0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
10dc0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10dd0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
10de0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
10df0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
10e00 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
10e10 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
10e20 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
10e30 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31  .** [H12341] [H1
10e40 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a  2343] [H12344].*
10e50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
10e60 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
10e70 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
10e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10e90 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
10ea0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
10eb0 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d  Queries {H12370}
10ec0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
10ed0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
10ee0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
10ef0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
10f00 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
10f10 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
10f20 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
10f30 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
10f40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
10f50 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
10f60 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
10f70 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
10f80 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
10f90 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
10fa0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
10fb0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
10fc0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
10fd0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
10fe0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
10ff0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
11000 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
11010 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
11020 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
11030 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
11040 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
11050 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
11060 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
11070 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
11080 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
11090 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
110a0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
110b0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
110c0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
110d0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
110e0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
110f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
11100 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
11110 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
11120 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
11130 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
11140 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
11150 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
11160 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
11170 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
11180 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
11190 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
111a0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
111b0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
111c0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
111d0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
111e0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
111f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
11200 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
11210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
11220 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
11230 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
11240 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
11250 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
11260 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
11270 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
11280 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
11290 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
112a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
112b0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
112c0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
112d0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
112e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
112f0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
11300 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
11310 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11320 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
11330 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
11340 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
11350 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
11360 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
11370 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
11380 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
11390 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
113a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
113b0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
113c0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
113d0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
113e0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
113f0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
11400 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
11410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
11420 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
11430 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
11440 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
11450 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
11460 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
11470 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
11480 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
11490 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
114a0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
114b0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
114c0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
114d0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
114e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
114f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
11500 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
11510 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
11520 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
11530 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
11540 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11550 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
11560 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
11570 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
11580 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11590 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
115a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
115b0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
115c0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
115d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
115e0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
115f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11600 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
11610 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
11620 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e>.**.** The sql
11630 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11640 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
11650 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
11660 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
11670 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
11680 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
11690 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
116a0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
116b0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
116c0 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61  r.  It returns a
116d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
116e0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
116f0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
11700 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
11710 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
11720 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
11730 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
11740 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
11750 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68  hould.** pass th
11760 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
11770 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
11780 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
11790 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
117a0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
117b0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
117c0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
117d0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
117e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
117f0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
11800 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
11810 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
11820 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
11830 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
11840 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
11850 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
11860 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
11870 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
11880 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
11890 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
118a0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
118b0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
118c0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
118d0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
118e0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
118f0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
11900 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
11910 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
11920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11930 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
11940 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
11950 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
11960 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
11970 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
11980 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
11990 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
119a0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
119b0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
119c0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
119d0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
119e0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
119f0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
11a00 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
11a10 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
11a20 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
11a30 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
11a40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
11a50 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73  errcode()] or [s
11a60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
11a70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
11a80 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31  ents:.** [H12371
11a90 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33  ] [H12373] [H123
11aa0 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31  74] [H12376] [H1
11ab0 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a  2379] [H12382].*
11ac0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
11ad0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
11ae0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
11af0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
11b00 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
11b10 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
11b20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
11b30 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
11b40 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
11b50 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
11b60 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
11b70 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
11b80 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
11b90 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
11ba0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
11bb0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
11bc0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
11bd0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
11be0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
11bf0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
11c00 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
11c10 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
11c20 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
11c30 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
11c40 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
11c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11c60 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
11c70 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
11c80 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20  ctions {H17400} 
11c90 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e  <S70000><S20000>
11ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
11cb0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
11cc0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
11cd0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
11ce0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
11cf0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11d00 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
11d10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
11d20 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
11d30 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
11d40 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
11d50 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
11d60 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
11d70 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
11d80 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
11d90 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
11da0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
11db0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
11dc0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
11dd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
11de0 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
11df0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
11e00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
11e10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11e20 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
11e30 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
11e40 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
11e50 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
11e60 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
11e70 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
11e80 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
11e90 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
11ea0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
11eb0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
11ec0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
11ed0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
11ee0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
11ef0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
11f00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
11f10 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
11f20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
11f30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
11f40 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
11f50 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
11f60 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
11f70 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
11f80 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
11f90 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
11fa0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
11fb0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
11fc0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
11fd0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
11fe0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
11ff0 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12000 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12010 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12020 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12030 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12040 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
12050 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
12060 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
12070 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
12080 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
12090 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
120a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
120b0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
120c0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
120d0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
120e0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
120f0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
12100 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12110 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12120 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
12130 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
12140 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
12150 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
12160 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
12170 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
12180 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
12190 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
121a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
121b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
121c0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
121d0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
121e0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
121f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
12200 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
12210 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
12220 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
12230 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
12240 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
12250 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
12260 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
12270 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
12280 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12290 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
122a0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
122b0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
122c0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
122d0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
122e0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
122f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
12300 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
12310 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
12320 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
12330 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
12340 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
12350 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
12360 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
12370 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
12380 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
12390 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
123a0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
123b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
123c0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
123d0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
123e0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
123f0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
12400 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
12410 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
12420 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
12430 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
12440 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
12450 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
12460 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
12470 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
12480 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
12490 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
124a0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
124b0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
124c0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
124d0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
124e0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
124f0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
12500 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12510 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
12520 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
12530 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
12540 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12550 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
12560 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
12570 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
12580 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12590 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
125a0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
125b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
125c0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
125d0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
125e0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
125f0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
12600 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
12610 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
12620 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
12630 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12640 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
12650 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
12660 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
12670 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
12680 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
12690 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
126a0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
126b0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
126c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
126d0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
126e0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
126f0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
12700 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
12710 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12720 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
12730 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
12740 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
12750 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
12760 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
12770 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
12780 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
12790 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
127a0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
127b0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
127c0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
127d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
127e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
127f0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
12800 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
12810 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
12820 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
12830 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
12840 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
12850 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
12860 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
12870 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
12880 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
12890 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
128a0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
128b0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
128c0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
128d0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
128e0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
128f0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
12900 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
12910 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
12920 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
12930 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
12940 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
12950 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
12960 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
12970 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
12980 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
12990 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
129a0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
129b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
129c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
129d0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
129e0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
129f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
12a00 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
12a10 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
12a20 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
12a30 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
12a40 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
12a50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12a60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12a70 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
12a80 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
12a90 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
12aa0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
12ab0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
12ac0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
12ad0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
12ae0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
12af0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
12b00 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
12b10 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
12b20 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
12b30 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
12b40 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
12b50 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
12b60 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
12b70 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
12b80 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
12b90 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
12ba0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
12bb0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
12bc0 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31  .** [H17403] [H1
12bd0 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a  7406] [H17407].*
12be0 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
12bf0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
12c00 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
12c10 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
12c20 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
12c30 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
12c40 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
12c50 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
12c60 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
12c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
12c80 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
12c90 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
12ca0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
12cb0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
12cc0 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
12cd0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
12ce0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
12cf0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
12d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
12d10 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
12d20 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
12d30 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
12d40 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
12d50 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
12d60 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
12d70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
12d80 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
12d90 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
12da0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
12db0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
12dc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12dd0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
12de0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
12df0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
12e00 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
12e10 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
12e20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
12e30 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
12e40 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
12e50 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
12e60 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
12e70 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
12e80 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
12e90 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
12ea0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
12eb0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
12ec0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
12ed0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
12ee0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
12ef0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
12f00 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
12f10 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
12f20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
12f30 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
12f40 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
12f50 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
12f60 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
12f70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
12f80 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
12f90 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
12fa0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
12fb0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
12fc0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
12fd0 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
12fe0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
12ff0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13000 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
13010 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
13020 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
13030 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
13040 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
13050 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
13060 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
13070 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
13080 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
13090 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
130a0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
130b0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
130c0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
130d0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
130e0 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
130f0 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
13100 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
13110 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13120 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
13130 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
13140 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
13150 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
13160 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
13170 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
13180 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
13190 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
131a0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
131b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
131c0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
131d0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
131e0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
131f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13200 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
13210 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
13220 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
13230 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
13240 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13250 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
13260 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
13270 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
13280 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13290 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
132a0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
132b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
132c0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
132d0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
132e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
132f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
13300 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
13310 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13320 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13330 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
13340 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
13350 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
13360 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
13370 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
13380 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
13390 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
133a0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
133b0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
133c0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
133d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
133e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
133f0 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
13400 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
13410 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13420 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13430 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
13440 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
13450 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
13460 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
13470 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
13480 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
13490 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
134a0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
134b0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
134c0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
134d0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
134e0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
134f0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
13500 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
13510 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13520 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
13530 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
13540 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
13550 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
13560 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
13570 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
13580 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
13590 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
135a0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
135b0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
135c0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
135d0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
135e0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
135f0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
13600 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
13610 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
13620 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
13630 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
13640 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13650 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
13660 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
13670 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
13680 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
13690 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
136a0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37  library..** {H17
136b0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
136c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
136d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
136e0 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
136f0 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
13700 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
13710 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
13720 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
13730 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
13740 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
13750 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
13760 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
13770 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
13780 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
13790 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
137a0 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
137b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
137c0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
137d0 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
137e0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
137f0 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
13800 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13810 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
13820 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
13830 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
13840 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
13850 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
13860 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
13870 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
13880 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
13890 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
138a0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
138b0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
138c0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
138d0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
138e0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
138f0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
13900 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
13910 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
13920 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
13930 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
13940 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
13950 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
13960 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
13970 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
13980 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
13990 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
139a0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
139b0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
139c0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
139d0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
139e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
139f0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
13a00 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
13a10 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
13a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13a30 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
13a40 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
13a50 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
13a60 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
13a70 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
13a80 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
13a90 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
13aa0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
13ab0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
13ac0 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34  [H17303] [H17304
13ad0 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33  ] [H17305] [H173
13ae0 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31  06] [H17310] [H1
13af0 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b  7312] [H17315] [
13b00 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33  H17318].** [H173
13b10 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31  21] [H17322] [H1
13b20 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7323].**.** The 
13b30 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
13b40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
13b50 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
13b60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
13b70 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13b80 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
13b90 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
13ba0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
13bb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
13bc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13bd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
13be0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
13bf0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
13c00 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
13c10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13c20 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
13c30 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
13c40 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
13c50 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
13c60 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
13c70 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
13c80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
13c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
13ca0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
13cb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
13cc0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
13cd0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
13ce0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
13cf0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
13d00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13d10 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
13d20 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
13d30 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
13d40 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
13d50 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
13d60 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
13d70 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
13d80 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
13d90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13da0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
13db0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
13dc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
13dd0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
13de0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
13df0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
13e00 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
13e10 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
13e20 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d  nts:.** [H17371]
13e30 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37   [H17373] [H1737
13e40 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73  4] [H17375].*/.s
13e50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
13e60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
13e70 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
13e80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
13e90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
13ea0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
13eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13ec0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
13ed0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
13ee0 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e  H17390} <S20000>
13ef0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
13f00 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
13f10 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
13f20 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
13f30 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
13f40 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
13f50 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
13f60 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
13f70 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
13f80 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
13f90 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
13fa0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
13fb0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
13fc0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
13fd0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
13fe0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
13ff0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
14000 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
14010 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
14020 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
14030 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
14040 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
14050 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
14060 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
14070 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
14080 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
14090 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
140a0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
140b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
140c0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
140d0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
140e0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
140f0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
14100 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
14110 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
14120 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
14130 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
14140 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
14150 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
14160 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
14170 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
14180 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
14190 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
141a0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
141b0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
141c0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
141d0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
141e0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
141f0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
14200 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
14210 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
14220 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a  ts:.** [H17392].
14230 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
14240 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
14250 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
14260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
14270 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
14280 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
14290 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31  s {H12500} <S701
142a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
142b0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
142c0 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
142d0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
142e0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
142f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14300 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
14310 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14320 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
14330 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
14340 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
14350 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
14360 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
14370 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
14380 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
14390 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
143a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
143b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
143c0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
143d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
143e0 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
143f0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
14400 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
14410 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
14420 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
14430 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
14440 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
14450 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
14460 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
14470 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
14480 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
14490 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
144a0 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
144b0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
144c0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
144d0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
144e0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
144f0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
14500 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
14510 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
14520 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
14530 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
14540 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
14550 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
14560 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
14570 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
14580 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
14590 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
145a0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  ith an error.  I
145b0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
145c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
145d0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
145e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
145f0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
14600 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
14610 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
14620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
14630 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
14640 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
14650 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
14660 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14670 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
14680 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
14690 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
146a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
146b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
146c0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
146d0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
146e0 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
146f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
14700 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
14710 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
14720 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
14730 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
14740 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
14750 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
14760 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
14770 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
14780 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
14790 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
147a0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
147b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
147c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
147d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
147e0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
147f0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
14800 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
14810 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14820 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
14830 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14840 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
14850 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
14860 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
14870 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
14880 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
14890 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
148a0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
148b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
148c0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
148d0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
148e0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
148f0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
14900 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
14910 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
14920 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
14930 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
14940 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
14950 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  zed..**.** If th
14960 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
14970 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
14980 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
14990 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
149a0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
149b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
149c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
149d0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
149e0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
149f0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
14a00 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
14a10 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
14a20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
14a30 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
14a40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
14a50 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
14a60 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
14a70 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
14a80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
14a90 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
14aa0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
14ab0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
14ac0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
14ad0 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e  ** If the action
14ae0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
14af0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
14b00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
14b10 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
14b20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
14b30 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
14b40 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
14b50 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
14b60 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
14b70 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
14b80 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
14b90 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
14ba0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
14bb0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
14bc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14bd0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
14be0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
14bf0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
14c00 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
14c10 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
14c20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
14c30 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
14c40 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
14c50 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
14c60 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
14c70 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
14c80 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
14c90 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
14ca0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
14cb0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
14cc0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
14cd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
14ce0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
14cf0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
14d00 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
14d10 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
14d20 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
14d30 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
14d40 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
14d50 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
14d60 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
14d70 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
14d80 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
14d90 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
14da0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
14db0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
14dc0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
14dd0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
14de0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
14df0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
14e00 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
14e10 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
14e20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
14e30 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
14e40 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
14e50 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
14e60 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
14e70 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
14e80 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
14e90 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
14ea0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
14eb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
14ec0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
14ed0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
14ee0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
14ef0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
14f00 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
14f10 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
14f20 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
14f30 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
14f40 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
14f50 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
14f60 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
14f70 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
14f80 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
14f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
14fa0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
14fb0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
14fc0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
14fd0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
14fe0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
14ff0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
15000 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
15010 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
15020 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
15030 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15040 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
15050 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
15060 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
15070 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
15080 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
15090 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
150a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
150b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
150c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
150d0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
150e0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
150f0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
15100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15110 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
15120 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
15130 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
15140 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
15150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15160 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
15170 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
15180 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
15190 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
151a0 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  eprepared during
151b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
151c0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
151d0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
151e0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
151f0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
15200 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
15210 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
15220 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
15230 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
15240 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
15250 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
15260 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
15270 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15280 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
15290 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
152a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
152b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
152c0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
152d0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
152e0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
152f0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
15300 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
15310 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
15320 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
15330 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
15340 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
15350 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
15360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
15370 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
15380 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
15390 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
153a0 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
153b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 30  ments:.** [H1250
153c0 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31 32  1] [H12502] [H12
153d0 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b 48  503] [H12504] [H
153e0 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d 20  12505] [H12506] 
153f0 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31 30  [H12507] [H12510
15400 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b 48  ].** [H12511] [H
15410 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d 20  12512] [H12520] 
15420 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32 32  [H12521] [H12522
15430 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
15440 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
15450 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
15460 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
15470 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
15480 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
15490 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
154a0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
154b0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
154c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
154d0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
154e0 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c  Codes {H12590} <
154f0 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H12500>.**.** Th
15500 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
15510 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
15520 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15530 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
15540 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
15550 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
15560 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
15570 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
15580 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
15590 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
155a0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
155b0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
155c0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
155d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
155e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
155f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
15600 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
15610 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
15620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15630 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
15640 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
15650 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
15660 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
15670 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
15680 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
15690 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
156a0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
156b0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
156c0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
156d0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20  er Action Codes 
156e0 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30  {H12550} <H12500
156f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  >.**.** The [sql
15700 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15710 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
15720 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
15730 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
15740 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
15750 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
15760 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
15770 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
15780 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
15790 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
157a0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
157b0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
157c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
157d0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
157e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
157f0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
15800 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
15810 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
15820 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15830 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
15840 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
15850 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
15860 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
15870 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
15880 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
15890 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
158a0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
158b0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
158c0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
158d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
158e0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
158f0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
15900 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
15910 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
15920 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15930 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
15940 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
15950 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
15960 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15970 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15980 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
15990 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
159a0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
159b0 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61  e.  The 6th para
159c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
159d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
159e0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
159f0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
15a00 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
15a10 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
15a20 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
15a30 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
15a40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
15a50 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
15a60 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
15a70 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
15a80 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71   code..**.** Req
15a90 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
15aa0 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20  12551] [H12552] 
15ab0 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34  [H12553] [H12554
15ac0 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ].*/./**********
15ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15ae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15af0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
15b00 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
15b10 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
15b20 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
15b30 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
15b40 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
15b50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15b70 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
15b80 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
15b90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15ba0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15bb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15bc0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
15bd0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
15be0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
15bf0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15c00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15c10 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
15c20 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
15c30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
15c40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c60 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
15c70 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
15c80 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
15c90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
15ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
15cb0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
15cc0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
15cd0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
15ce0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15d00 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
15d10 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
15d20 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
15d30 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
15d50 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
15d60 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
15d70 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
15d80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15d90 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
15da0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
15db0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
15dc0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15dd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15de0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
15df0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
15e00 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
15e10 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
15e20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15e30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
15e40 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
15e50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15e60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15e70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15e80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15e90 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
15ea0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
15eb0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
15ec0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15ed0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15ee0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
15ef0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15f00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15f10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15f20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15f30 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
15f40 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
15f50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15f60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15f70 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
15f80 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
15f90 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15fa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15fb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15fc0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
15fd0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
15fe0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
15ff0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16010 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
16020 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
16030 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
16040 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16050 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16060 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
16070 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
16080 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
16090 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
160a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160b0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
160c0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
160d0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
160e0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
160f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16100 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
16110 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
16120 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
16130 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
16140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
16150 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
16160 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
16170 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
16180 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
161a0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
161b0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
161c0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
161d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
161e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
161f0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
16200 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
16210 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
16220 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
16230 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
16240 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
16250 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
16260 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
16270 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16280 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
16290 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
162a0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
162b0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
162c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
162d0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
162e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
162f0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
16300 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
16310 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
16320 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
16330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
16340 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16350 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16360 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16370 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
16380 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
16390 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
163a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
163b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
163c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
163d0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
163e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
163f0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
16400 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16410 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
16420 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
16430 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16440 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
16450 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16460 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
16470 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
16480 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
16490 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
164a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
164b0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
164c0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
164d0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
164e0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
164f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16500 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
16510 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
16520 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
16530 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
16540 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
16550 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
16560 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30  ns {H12280} <S60
16570 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  400>.** EXPERIME
16580 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  NTAL.**.** These
16590 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
165a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
165b0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
165c0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
165d0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
165e0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
165f0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
16600 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nts..**.** The c
16610 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
16620 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
16630 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
16640 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
16650 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
16660 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
16670 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
16680 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
16690 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  p()]..** The cal
166a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
166b0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
166c0 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
166d0 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20  ment text.** as 
166e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
166f0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
16700 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ting.  Additiona
16710 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75  l callbacks occu
16720 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
16730 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
16740 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
16750 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
16760 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
16770 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
16780 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
16790 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
167a0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gger..**.** The 
167b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
167c0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
167d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
167e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
167f0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
16800 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
16810 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   The profile cal
16820 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
16830 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
16840 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
16850 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
16860 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
16870 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
16880 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
16890 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ook to run..**.*
168a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
168b0 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32  ** [H12281] [H12
168c0 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48  282] [H12283] [H
168d0 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20  12284] [H12285] 
168e0 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38  [H12287] [H12288
168f0 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48  ] [H12289].** [H
16900 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45  12290].*/.SQLITE
16910 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
16920 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
16930 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
16940 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
16950 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
16960 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
16970 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
16980 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
16990 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
169a0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
169b0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
169c0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
169d0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
169e0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
169f0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
16a00 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34  s {H12910} <S604
16a10 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
16a20 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
16a30 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
16a40 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70  ction - the.** p
16a50 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
16a60 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b   - that is invok
16a70 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
16a80 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72  during long.** r
16a90 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
16aa0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
16ab0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
16ac0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
16ad0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
16ae0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
16af0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
16b00 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
16b10 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
16b20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
16b30 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uery..**.** If t
16b40 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
16b50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
16b60 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
16b70 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
16b80 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
16b90 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
16ba0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
16bb0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
16bc0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
16bd0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
16be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
16bf0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
16c00 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
16c10 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
16c20 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
16c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
16c40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
16c50 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
16c60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
16c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16c80 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
16c90 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
16ca0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
16cb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16cc0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
16cd0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
16ce0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
16cf0 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  h..**.** Require
16d00 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 31  ments:.** [H1291
16d10 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31 32  1] [H12912] [H12
16d20 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b 48  913] [H12914] [H
16d30 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d 20  12915] [H12916] 
16d40 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31 38  [H12917] [H12918
16d50 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ].**.*/.void sql
16d60 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
16d70 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
16d80 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
16d90 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
16da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
16db0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
16dc0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
16dd0 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12700} <S40200>
16de0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
16df0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
16e00 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
16e10 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
16e20 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
16e30 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
16e40 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  nt. The filename
16e50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
16e60 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
16e70 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
16e80 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
16e90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
16ea0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
16eb0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
16ec0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
16ed0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20  te3_open16(). A 
16ee0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16ef0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
16f00 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
16f10 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
16f20 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
16f30 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
16f40 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
16f50 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
16f60 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
16f70 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
16f80 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
16f90 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
16fa0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
16fb0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
16fc0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
16fd0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
16fe0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
16ff0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
17000 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
17010 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
17020 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
17030 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
17040 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
17050 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
17060 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
17070 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  d.  The.** [sqli
17080 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
17090 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
170a0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
170b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
170c0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
170d0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
170e0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
170f0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
17100 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
17110 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
17120 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
17130 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
17140 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
17150 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
17160 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
17170 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
17180 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
17190 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
171a0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
171b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
171c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
171d0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
171e0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
171f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
17200 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17210 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
17220 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
17230 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
17240 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
17250 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
17260 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
17270 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
17280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17290 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
172a0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
172b0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
172c0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
172d0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
172e0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
172f0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
17300 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
17310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17320 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73  tion.  The flags
17330 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74   parameter can t
17340 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
17350 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
17360 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
17370 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
17380 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
17390 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
173a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
173b0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
173c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
173d0 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
173e0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
173f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
17400 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
17410 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
17420 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
17430 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
17440 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
17450 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
17460 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
17470 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
17480 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
17490 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
174a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
174b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
174c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
174d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
174e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
174f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
17500 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
17510 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
17520 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
17530 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
17540 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
17550 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
17560 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
17570 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
17580 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
17590 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
175a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
175b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
175c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
175d0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
175e0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
175f0 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
17600 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
17610 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
17620 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
17630 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
17640 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
17650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
17660 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
17670 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
17680 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
17690 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
176a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
176b0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
176c0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
176d0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
176e0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
176f0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
17700 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
17710 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
17720 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
17730 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
17740 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
17750 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
17760 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
17770 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
17780 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
17790 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
177a0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
177b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
177c0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
177d0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
177e0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
177f0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
17800 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
17810 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
17820 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
17830 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
17840 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a  -time.  If the.*
17850 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
17860 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
17870 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
17880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17890 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
178a0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
178b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
178c0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
178d0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
178e0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
178f0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
17900 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
17910 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
17920 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
17930 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
17940 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
17950 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
17960 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
17970 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
17980 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72  .  This in-memor
17990 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
179a0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
179b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
179c0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
179d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
179e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
179f0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
17a00 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
17a10 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
17a20 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
17a30 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
17a40 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
17a50 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
17a60 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
17a70 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
17a80 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
17a90 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
17aa0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
17ab0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
17ac0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
17ad0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
17ae0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
17af0 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ty..**.** If the
17b00 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
17b10 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
17b20 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
17b30 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
17b40 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
17b50 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68   be created.  Th
17b60 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
17b70 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
17b80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
17b90 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
17ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17bb0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
17bc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  d..**.** The fou
17bd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
17be0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
17bf0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
17c00 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
17c10 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
17c20 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
17c30 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
17c40 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
17c50 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
17c60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
17c70 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68  ould use.  If th
17c80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17c90 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
17ca0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
17cb0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
17cc0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
17cd0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
17ce0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
17cf0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
17d00 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
17d10 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
17d20 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
17d30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
17d40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
17d50 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
17d60 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
17d70 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
17d80 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
17d90 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
17da0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
17db0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
17dc0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
17dd0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
17de0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
17df0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
17e00 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
17e10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
17e20 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
17e30 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31 5d  nts:.** [H12701]
17e40 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32 37 30   [H12702] [H1270
17e50 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48 31 32  3] [H12704] [H12
17e60 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b 48  706] [H12707] [H
17e70 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31 5d 0a  12709] [H12711].
17e80 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48 31 32  ** [H12712] [H12
17e90 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b 48  713] [H12714] [H
17ea0 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39 5d 20  12717] [H12719] 
17eb0 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37 32 33  [H12721] [H12723
17ec0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
17ed0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
17ee0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
17ef0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
17f00 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
17f10 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
17f20 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
17f30 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
17f40 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
17f50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
17f60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
17f70 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
17f80 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
17f90 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
17fa0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
17fb0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
17fc0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
17fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
17fe0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
17ff0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
18000 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
18010 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
18020 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
18030 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
18040 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
18050 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
18060 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
18070 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
18080 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
18090 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
180a0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
180b0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
180c0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
180d0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
180e0 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36  ges {H12800} <S6
180f0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
18100 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
18110 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
18120 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
18130 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
18140 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
18150 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
18160 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
18170 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
18180 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
18190 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
181a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
181b0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
181c0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
181d0 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
181e0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
181f0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
18200 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
18210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
18220 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
18230 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
18240 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
18250 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
18260 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
18270 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
18280 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
18290 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
182a0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
182b0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
182c0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
182d0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
182e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
182f0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
18300 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
18310 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
18320 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
18330 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
18340 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
18350 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
18360 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
18370 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * Memory to hold
18380 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
18390 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
183a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
183b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
183c0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
183d0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
183e0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
183f0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
18400 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
18410 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
18420 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
18430 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
18440 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
18450 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
18460 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
18470 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
18480 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
18490 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
184a0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
184b0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
184c0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
184d0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
184e0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
184f0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
18500 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
18510 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
18520 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
18530 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
18540 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
18550 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
18560 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
18570 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
18580 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
18590 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
185a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
185b0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
185c0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
185d0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
185e0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
185f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18600 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
18610 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
18620 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
18630 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
18640 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
18650 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
18660 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
18670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
18680 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
18690 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
186a0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
186b0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
186c0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
186d0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
186e0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
186f0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
18700 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
18710 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
18720 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
18730 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
18740 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
18750 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
18760 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
18770 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
18780 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
18790 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  t be set..**.** 
187a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
187b0 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32 38 30   [H12801] [H1280
187c0 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48 31 32  2] [H12803] [H12
187d0 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b 48  807] [H12808] [H
187e0 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71  12809].*/.int sq
187f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
18800 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
18810 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
18820 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
18830 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
18840 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
18850 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
18860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
18870 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
18880 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18890 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
188a0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30  ent Object {H130
188b0 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20  00} <H13010>.** 
188c0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
188d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
188e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
188f0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
18900 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
18910 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
18920 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
18930 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
18940 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
18950 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
18960 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
18970 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
18980 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
18990 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
189a0 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
189b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
189c0 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
189d0 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
189e0 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
189f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
18a00 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
18a10 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
18a20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18a30 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
18a40 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
18a50 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
18a60 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
18a70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
18a80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
18a90 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
18aa0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
18ab0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
18ac0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
18ad0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
18ae0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
18af0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
18b00 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
18b10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
18b20 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
18b30 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
18b40 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
18b50 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
18b60 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
18b70 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
18b80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
18b90 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
18ba0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
18bb0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
18bc0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
18bd0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
18be0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
18bf0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
18c00 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
18c10 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
18c20 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
18c30 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
18c40 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32  its {H12760} <S2
18c50 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
18c60 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
18c70 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
18c80 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
18c90 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
18ca0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
18cb0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
18cc0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
18cd0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
18ce0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
18cf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
18d00 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
18d10 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
18d20 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
18d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
18d40 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
18d50 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
18d60 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
18d70 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
18d80 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
18d90 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
18da0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
18db0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
18dc0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
18dd0 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
18de0 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
18df0 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
18e00 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
18e10 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
18e20 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
18e30 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
18e40 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
18e50 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
18e60 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
18e70 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
18e80 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
18e90 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20  nd].** set by a 
18ea0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
18eb0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
18ec0 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d  o named .** [lim
18ed0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
18ee0 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  _XYZ]..** (The "
18ef0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
18f00 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
18f10 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20  to "_MAX_".).** 
18f20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
18f30 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
18f40 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
18f50 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
18f60 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
18f70 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
18f80 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  per limit..**.**
18f90 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73   Run time limits
18fa0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
18fb0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
18fc0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
18fd0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
18fe0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
18ff0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
19000 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
19010 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
19020 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
19030 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
19040 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
19050 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
19060 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
19070 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
19080 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
19090 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
190a0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
190b0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
190c0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
190d0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
190e0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
190f0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
19100 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
19110 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
19120 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
19130 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
19140 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
19150 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
19160 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
19170 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
19180 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
19190 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
191a0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
191b0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
191c0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
191d0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
191e0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
191f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
19200 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
19210 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
19220 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
19230 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
19240 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
19250 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
19260 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
19270 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
19280 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
19290 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
192a0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
192b0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
192c0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
192d0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
192e0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
192f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
19300 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31 32  ** [H12762] [H12
19310 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a 2f  766] [H12769].*/
19320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
19330 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
19340 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
19350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19360 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
19370 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31  t Categories {H1
19380 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a  2790} <H12760>.*
19390 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
193a0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
193b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
193c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
193d0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
193e0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
193f0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
19400 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
19410 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
19420 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
19430 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
19440 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
19450 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
19460 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
19470 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
19480 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
19490 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
194a0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
194b0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
194c0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
194d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
194e0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
194f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
19500 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
19510 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
19520 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a  le row.<dd>.**.*
19530 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
19540 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
19550 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
19560 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
19570 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19580 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19590 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
195a0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
195b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
195c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
195d0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
195e0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
195f0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
19600 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
19610 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
19620 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
19630 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
19640 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
19650 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
19660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19670 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
19680 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
19690 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
196a0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
196b0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
196c0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a  xpression.</dd>.
196d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
196e0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
196f0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
19700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
19710 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
19720 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
19730 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
19740 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19750 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
19760 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
19770 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
19780 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
19790 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
197a0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
197b0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
197c0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
197d0 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
197e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
197f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
19800 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
19810 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
19820 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
19830 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  function.</dd>.*
19840 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
19850 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
19860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
19870 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
19880 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
19890 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 3c  hed databases].<
198a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
198b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
198c0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
198d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
198e0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
198f0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
19900 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
19910 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
19920 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
19930 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19940 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
19950 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
19960 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
19970 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
19980 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
19990 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
199a0 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
199b0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
199c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
199d0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
199e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
199f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a00 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
19a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19a20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
19a30 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
19a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19a50 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
19a60 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
19a70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
19a80 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
19a90 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
19aa0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
19ab0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
19ac0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
19ad0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
19ae0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
19af0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
19b00 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
19b10 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
19b20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
19b30 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
19b40 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
19b50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
19b60 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
19b70 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
19b80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
19b90 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
19ba0 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
19bb0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
19bc0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
19bd0 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
19be0 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
19bf0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
19c00 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
19c10 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
19c20 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
19c30 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
19c40 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
19c50 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
19c60 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
19c70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
19c80 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
19c90 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
19ca0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
19cb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
19cc0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
19cd0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
19ce0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
19cf0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
19d00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
19d10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
19d20 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
19d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19d40 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
19d50 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
19d60 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
19d70 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
19d80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
19d90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
19da0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
19db0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
19dc0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
19dd0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
19de0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19df0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
19e00 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
19e10 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
19e20 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
19e30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
19e40 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
19e50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
19e60 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
19e70 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
19e80 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
19e90 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
19ea0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
19eb0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
19ec0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
19ed0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
19ee0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
19ef0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
19f00 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
19f10 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
19f20 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
19f30 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
19f40 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
19f50 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
19f60 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
19f70 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
19f80 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
19f90 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
19fa0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
19fb0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
19fc0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
19fd0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
19fe0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
19ff0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1a000 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1a010 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1a020 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1a030 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1a040 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1a050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1a060 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1a070 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1a080 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1a090 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1a0a0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bytes..**.** If 
1a0b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1a0c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1a0d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1a0e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1a0f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1a100 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1a110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1a120 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1a130 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1a140 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1a150 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1a160 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1a170 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1a180 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1a190 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1a1a0 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1a1b0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1a1c0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1a1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a1e0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1a1f0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1a200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1a210 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1a220 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1a230 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1a240 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1a250 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1a260 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1a270 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1a280 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1a290 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1a2a0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1a2b0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
1a2c0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1a2d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1a2e0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1a2f0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1a300 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1a310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1a320 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1a330 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1a340 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
1a350 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
1a360 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
1a370 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1a380 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73  turned, otherwis
1a390 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1a3a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1a3b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a3c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1a3d0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1a3e0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1a3f0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1a400 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1a410 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1a420 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1a430 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1a440 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1a450 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1a460 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1a470 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1a480 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
1a490 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1a4a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a4b0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
1a4c0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
1a4d0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1a4e0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
1a4f0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
1a500 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
1a510 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
1a520 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a530 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
1a540 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
1a550 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
1a560 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1a570 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
1a580 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1a590 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1a5a0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1a5b0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1a5c0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1a5d0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1a5e0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1a5f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1a600 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1a610 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1a620 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1a630 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
1a640 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1a650 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1a660 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1a670 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1a680 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1a690 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1a6a0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1a6b0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1a6c0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1a6d0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1a6e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1a6f0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1a700 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1a710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a720 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1a730 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1a740 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1a750 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1a760 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1a770 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1a780 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1a790 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1a7a0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1a7b0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1a7c0 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1a7d0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
1a7e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1a7f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a800 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1a810 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1a820 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1a830 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1a840 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54  error codes].  T
1a850 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1a860 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1a870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a880 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1a890 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1a8a0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1a8b0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f  t code.** and yo
1a8c0 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
1a8d0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1a8e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1a8f0 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
1a900 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
1a910 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1a920 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1a930 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1a940 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1a950 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1a960 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1a970 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1a980 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1a990 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
1a9a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  /ol>.**.** Requi
1a9b0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1a9c0 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20 5b 48  011] [H13012] [H
1a9d0 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34 5d 20  13013] [H13014] 
1a9e0 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30 31 36  [H13015] [H13016
1a9f0 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31 33 30  ] [H13019] [H130
1aa00 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  21].**.*/.int sq
1aa10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1aa20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1aa30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1aa40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1aa50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1aa60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1aa70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1aa80 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1aa90 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1aaa0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1aab0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1aac0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1aad0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1aae0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1aaf0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1ab00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1ab10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1ab20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1ab30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1ab40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1ab50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1ab60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1ab70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1ab80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1ab90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1aba0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1abb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1abc0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1abd0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1abe0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1abf0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1ac00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1ac10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1ac20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1ac30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1ac40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1ac50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1ac60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1ac70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1ac80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1ac90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1aca0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1acb0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1acc0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1acd0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ace0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1acf0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1ad00 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1ad10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1ad20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1ad30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1ad40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1ad50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1ad60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1ad70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1ad80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1ad90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1ada0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1adb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1adc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1add0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1ade0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1adf0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1ae00 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1ae10 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1ae20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1ae30 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1ae40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ae50 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1ae60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ae70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ae80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ae90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1aea0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1aeb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1aec0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1aed0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1aee0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1aef0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1af00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1af10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1af20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1af30 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1af40 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
1af50 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
1af60 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1af70 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
1af80 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1af90 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1afa0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1afb0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1afc0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1afd0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
1afe0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
1aff0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
1b000 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1b010 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b020 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1b030 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1b040 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1b050 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b 48 31  .** [H13101] [H1
1b060 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d 0a 2a  3102] [H13103].*
1b070 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1b080 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1b090 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1b0a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b0b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1b0c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1b0d0 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
1b0e0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1b0f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1b100 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1b110 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1b120 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1b130 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1b140 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1b150 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1b160 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1b170 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1b180 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1b190 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1b1a0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1b1b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1b1c0 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
1b1d0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1b1e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1b1f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1b200 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1b210 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1b220 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1b230 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1b240 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1b250 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1b260 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1b270 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1b280 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1b290 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1b2a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1b2b0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1b2c0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1b2d0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1b2e0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1b2f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1b300 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1b310 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1b320 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1b330 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1b340 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1b350 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1b360 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1b370 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1b380 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1b390 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1b3a0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1b3b0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1b3c0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1b3d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1b3e0 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1b3f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1b400 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1b410 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b420 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1b430 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1b440 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1b450 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b460 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1b470 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1b480 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1b490 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1b4a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1b4b0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1b4c0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1b4d0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1b4e0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1b4f0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1b500 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1b510 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1b520 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1b530 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1b540 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1b550 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1b560 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1b570 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1b580 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1b590 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1b5a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1b5b0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1b5c0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1b5d0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1b5e0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1b5f0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1b600 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1b610 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1b620 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1b630 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1b640 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1b650 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1b660 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1b670 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1b680 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1b690 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1b6a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b6b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1b6c0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1b6d0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1b6e0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1b6f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1b700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1b710 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1b720 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1b730 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b740 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1b750 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1b760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1b770 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1b780 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1b790 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1b7a0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1b7b0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1b7c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1b7d0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1b7e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1b7f0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1b800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1b810 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1b820 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1b830 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1b840 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1b850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1b860 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1b870 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1b880 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1b890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b8a0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1b8b0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
1b8c0 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
1b8d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1b8e0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1b8f0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1b900 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1b910 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1b920 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1b930 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1b940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1b950 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1b960 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1b970 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1b980 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1b990 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1b9a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1b9b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1b9c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1b9d0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1b9e0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1b9f0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1ba00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1ba10 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1ba20 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1ba30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1ba40 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1ba50 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1ba60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ba70 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1ba80 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1ba90 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1baa0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1bab0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1bac0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1bad0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1bae0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1baf0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1bb00 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1bb10 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1bb20 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
1bb30 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
1bb40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1bb50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1bb60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1bb70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1bb80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1bb90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1bba0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1bbb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1bbc0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
1bbd0 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1bbe0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1bbf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bc00 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1bc10 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1bc20 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1bc30 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69   a [parameter] i
1bc40 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
1bc50 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
1bc60 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1bc70 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1bc80 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1bc90 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1bca0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1bcb0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
1bcc0 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
1bcd0 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
1bce0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
1bcf0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
1bd00 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
1bd10 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
1bd20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1bd30 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1bd40 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1bd50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1bd60 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1bd70 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1bd80 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1bd90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1bda0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1bdb0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1bdc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1bdd0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1bde0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1bdf0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1be00 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1be10 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1be20 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1be30 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1be40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1be50 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1be60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1be70 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
1be80 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1be90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
1bea0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
1beb0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
1bec0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1bed0 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
1bee0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1bef0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1bf00 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1bf10 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1bf20 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1bf30 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1bf40 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1bf50 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1bf60 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
1bf70 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1bf80 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1bf90 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1bfa0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1bfb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1bfc0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
1bfd0 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
1bfe0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1bff0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1c000 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1c010 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
1c020 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
1c030 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
1c040 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1c050 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
1c060 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1c070 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
1c080 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
1c090 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
1c0a0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1c0b0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1c0c0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1c0d0 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
1c0e0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
1c0f0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
1c100 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
1c110 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1c120 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1c130 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
1c140 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
1c150 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1c160 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
1c170 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
1c180 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
1c190 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1c1a0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
1c1b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1c1c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
1c1d0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
1c1e0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
1c1f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
1c200 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1c210 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1c220 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
1c230 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1c240 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1c250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c260 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1c270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1c280 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1c290 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1c2a0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1c2b0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1c2c0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1c2d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
1c2e0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1c2f0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1c300 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1c310 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1c320 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1c330 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1c340 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1c350 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1c360 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1c370 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1c380 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
1c390 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1c3a0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1c3b0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1c3c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1c3d0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1c3e0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1c3f0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1c400 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1c410 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1c420 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1c430 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
1c440 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1c450 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1c460 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1c470 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1c480 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1c490 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
1c4a0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1c4b0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1c4c0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1c4d0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
1c4e0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
1c4f0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
1c500 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
1c510 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
1c520 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
1c530 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1c540 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1c550 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1c560 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
1c570 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
1c580 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
1c590 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
1c5a0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
1c5b0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
1c5c0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
1c5d0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
1c5e0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
1c5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1c600 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
1c610 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
1c620 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c630 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
1c640 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
1c650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
1c660 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
1c670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1c680 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
1c690 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
1c6a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
1c6b0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
1c6c0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1c6d0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1c6e0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1c6f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c700 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c710 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1c720 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
1c730 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
1c740 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
1c750 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1c760 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1c770 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1c780 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1c790 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
1c7a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1c7b0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1c7c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1c7d0 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
1c7e0 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
1c7f0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1c800 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
1c810 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
1c820 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
1c830 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
1c840 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
1c850 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
1c860 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
1c870 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
1c880 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
1c890 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
1c8a0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
1c8b0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
1c8c0 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
1c8d0 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
1c8e0 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
1c8f0 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
1c900 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
1c910 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1c920 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
1c930 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
1c940 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
1c950 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
1c960 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1c970 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1c980 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1c990 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1c9a0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
1c9b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1c9c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1c9d0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1c9e0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d  nts:.** [H13506]
1c9f0 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31   [H13509] [H1351
1ca00 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33  2] [H13515] [H13
1ca10 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48  518] [H13521] [H
1ca20 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a  13524] [H13527].
1ca30 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33  ** [H13530] [H13
1ca40 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48  533] [H13536] [H
1ca50 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20  13539] [H13542] 
1ca60 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38  [H13545] [H13548
1ca70 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f  ] [H13551].**.*/
1ca80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ca90 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1caa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1cab0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1cac0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1cad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1cae0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1caf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1cb00 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1cb10 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1cb20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1cb30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1cb40 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1cb50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1cb60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1cb70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1cb80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1cb90 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1cba0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1cbb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1cbc0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1cbd0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1cbe0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1cbf0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1cc00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cc10 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1cc20 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1cc30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1cc40 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1cc50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cc60 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1cc70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1cc80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1cc90 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1cca0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1ccb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ccc0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1ccd0 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
1cce0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1ccf0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1cd00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
1cd10 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1cd20 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
1cd30 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
1cd40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1cd50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1cd60 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
1cd70 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
1cd80 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
1cd90 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
1cda0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
1cdb0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
1cdc0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
1cdd0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
1cde0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
1cdf0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
1ce00 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
1ce10 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
1ce20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
1ce30 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
1ce40 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
1ce50 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
1ce60 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
1ce70 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
1ce80 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
1ce90 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
1cea0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1ceb0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
1cec0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
1ced0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
1cee0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
1cef0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
1cf00 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
1cf10 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1cf20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1cf30 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1cf40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1cf50 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1cf60 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1cf70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1cf80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1cf90 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1cfa0 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e  * [H13601].*/.in
1cfb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1cfc0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
1cfd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1cfe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cff0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
1d000 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
1d010 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1d020 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1d030 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d040 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
1d050 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
1d060 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
1d070 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d080 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
1d090 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1d0a0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
1d0b0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1d0c0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
1d0d0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
1d0e0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
1d0f0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1d100 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1d110 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
1d120 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
1d130 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
1d140 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
1d150 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
1d160 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
1d170 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
1d180 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
1d190 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1d1a0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1d1b0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1d1c0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
1d1d0 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
1d1e0 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
1d1f0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
1d200 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1d210 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1d220 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1d230 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1d240 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1d250 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1d260 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1d270 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1d280 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1d290 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1d2a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1d2b0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
1d2c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1d2d0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1d2e0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1d2f0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1d300 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1d310 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1d320 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1d330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d340 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1d350 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1d360 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1d370 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1d380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1d390 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1d3a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1d3b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d3c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1d3d0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1d3e0 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f  * [H13621].*/.co
1d3f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d400 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d410 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1d420 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
1d430 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
1d440 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
1d450 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
1d460 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30  me {H13640} <S70
1d470 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  300>.**.** Retur
1d480 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1d490 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1d4a0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1d4b0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
1d4c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1d4d0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1d4e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1d4f0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1d500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d510 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1d520 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
1d530 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1d540 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1d550 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
1d560 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1d570 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1d580 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1d590 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1d5a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1d5b0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1d5c0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1d5d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d5e0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1d5f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1d600 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1d610 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1d620 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1d630 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1d640 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1d650 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d660 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1d670 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1d680 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a  .** [H13641].*/.
1d690 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1d6a0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1d6b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d6c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1d6d0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
1d6e0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
1d6f0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
1d700 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
1d710 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30  {H13660} <S70300
1d720 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79  >.**.** Contrary
1d730 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
1d740 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
1d750 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
1d760 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
1d770 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1d780 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
1d790 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
1d7a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1d7b0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
1d7c0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
1d7d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
1d7e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71   NULL..**.** Req
1d7f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1d800 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13661].*/.int sq
1d810 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1d820 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
1d830 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1d840 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1d850 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
1d860 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d  ult Set {H13710}
1d870 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
1d880 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
1d890 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1d8a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
1d8b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
1d8c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1d8d0 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75  ement]. This rou
1d8e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
1d8f0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
1d900 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
1d910 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
1d920 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
1d930 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
1d940 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ])..**.** Requir
1d950 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1d960 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  11].*/.int sqlit
1d970 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1d980 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1d990 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1d9a0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
1d9b0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
1d9c0 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
1d9d0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
1d9e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d9f0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
1da00 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
1da10 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
1da20 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1da30 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
1da40 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
1da50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1da60 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1da70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1da80 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1da90 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1daa0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
1dab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1dac0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
1dad0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1dae0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1daf0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1db00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1db10 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
1db20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1db30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
1db40 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
1db50 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
1db60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1db70 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
1db80 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
1db90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
1dba0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
1dbb0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1dbc0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
1dbd0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
1dbe0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1dbf0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
1dc00 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
1dc10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1dc20 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
1dc30 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
1dc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1dc50 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
1dc60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1dc70 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
1dc80 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
1dc90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
1dca0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
1dcb0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
1dcc0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
1dcd0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
1dce0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
1dcf0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
1dd00 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
1dd10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1dd20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1dd30 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1dd40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1dd50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1dd60 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1dd70 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1dd80 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1dd90 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1dda0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1ddb0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1ddc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1ddd0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1dde0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1ddf0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1de00 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1de10 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
1de20 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1de30 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 33  ** [H13721] [H13
1de40 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48  723] [H13724] [H
1de50 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d 20  13725] [H13726] 
1de60 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73  [H13727].*/.cons
1de70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1de80 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
1de90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1dea0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1deb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1dec0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1ded0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
1dee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
1def0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
1df00 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
1df10 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13740} <S10700>.
1df20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1df30 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1df40 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1df50 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66  e what column of
1df60 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69   what.** table i
1df70 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65  n which database
1df80 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b   a result of a [
1df90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1dfa0 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
1dfb0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
1dfc0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
1dfd0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
1dfe0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
1dff0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
1e000 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
1e010 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61  ng.  The _databa
1e020 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
1e030 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
1e040 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
1e050 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
1e060 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
1e070 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
1e080 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
1e090 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
1e0a0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  umn name..** The
1e0b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1e0c0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1e0d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1e0e0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1e0f0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
1e100 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e110 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1e120 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1e130 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1e140 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1e150 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1e160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1e170 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1e180 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1e190 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1e1a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1e1b0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1e1c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1e1d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1e1e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1e1f0 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1e200 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1e210 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1e220 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1e230 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1e240 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1e250 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
1e260 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
1e270 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
1e280 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
1e290 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
1e2a0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
1e2b0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
1e2c0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
1e2d0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
1e2e0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
1e2f0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
1e300 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
1e310 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
1e320 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20  ** NULL.  These 
1e330 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
1e340 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
1e350 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
1e360 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
1e370 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73  ccurs.  Otherwis
1e380 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
1e390 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
1e3a0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1e3b0 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63  , table.** and c
1e3c0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
1e3d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
1e3e0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
1e3f0 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68  m..**.** As with
1e400 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
1e410 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
1e420 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
1e430 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
1e440 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
1e450 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
1e460 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
1e470 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
1e480 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
1e490 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
1e4a0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
1e4b0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1e4c0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1e4d0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1e4e0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
1e4f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1e500 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  fined..**.** {A1
1e510 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
1e520 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1e530 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1e540 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1e550 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
1e560 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
1e570 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1e580 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
1e590 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1e5a0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
1e5b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
1e5c0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1e5d0 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32  [H13741] [H13742
1e5e0 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37  ] [H13743] [H137
1e5f0 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31  44] [H13745] [H1
1e600 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a  3746] [H13748].*
1e610 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
1e620 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
1e630 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1e640 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e650 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
1e660 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
1e670 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
1e680 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
1e690 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e6a0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
1e6b0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
1e6c0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
1e6d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1e6e0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
1e6f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1e700 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1e710 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1e720 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1e730 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1e740 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
1e750 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1e760 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
1e770 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e780 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
1e790 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1e7a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1e7b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1e7c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1e7d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1e7e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1e7f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1e800 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1e810 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1e820 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1e830 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
1e840 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1e850 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e860 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
1e870 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
1e880 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30  y Result {H13760
1e890 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1e8a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1e8b0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
1e8c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1e8d0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1e8e0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
1e8f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
1e900 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1e910 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
1e920 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
1e930 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
1e940 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
1e950 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
1e960 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
1e970 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
1e980 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
1e990 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
1e9a0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
1e9b0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1e9c0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
1e9d0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
1e9e0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1e9f0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
1ea00 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1ea10 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
1ea20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
1ea30 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
1ea40 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  oded. {END}.**.*
1ea50 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  * For example, g
1ea60 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
1ea70 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
1ea80 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
1ea90 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
1eaa0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
1eab0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
1eac0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
1ead0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
1eae0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
1eaf0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
1eb00 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
1eb10 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
1eb20 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
1eb30 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
1eb40 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
1eb50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1eb60 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
1eb70 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
1eb80 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
1eb90 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
1eba0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
1ebb0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
1ebc0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
1ebd0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
1ebe0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
1ebf0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
1ec00 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
1ec10 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
1ec20 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
1ec30 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
1ec40 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
1ec50 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
1ec60 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
1ec70 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
1ec80 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
1ec90 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
1eca0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
1ecb0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
1ecc0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
1ecd0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
1ece0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
1ecf0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1ed00 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48 31 33  ** [H13761] [H13
1ed10 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f  762] [H13763].*/
1ed20 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1ed30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1ed40 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
1ed50 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1ed60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1ed70 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
1ed80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1ed90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1eda0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
1edb0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
1edc0 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
1edd0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
1ede0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1edf0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
1ee00 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
1ee10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1ee20 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1ee30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ee40 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
1ee50 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
1ee60 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
1ee70 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1ee80 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1ee90 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
1eea0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
1eeb0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
1eec0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
1eed0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
1eee0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
1eef0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
1ef00 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
1ef10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1ef20 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
1ef30 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
1ef40 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
1ef50 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
1ef60 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
1ef70 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
1ef80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ef90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1efa0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
1efb0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
1efc0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
1efd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1efe0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1eff0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
1f000 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
1f010 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
1f020 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f030 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
1f040 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
1f050 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1f060 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
1f070 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
1f080 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
1f090 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1f0a0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1f0b0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
1f0c0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
1f0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
1f0e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
1f0f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1f100 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
1f110 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
1f120 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
1f130 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
1f140 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
1f150 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1f160 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
1f170 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
1f180 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
1f190 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
1f1a0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
1f1b0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
1f1c0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
1f1d0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
1f1e0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
1f1f0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
1f200 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
1f210 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
1f220 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
1f230 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
1f240 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1f250 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
1f260 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
1f270 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
1f280 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
1f290 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
1f2a0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
1f2b0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
1f2c0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
1f2d0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
1f2e0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
1f2f0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
1f300 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
1f310 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
1f320 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
1f330 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
1f340 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
1f350 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
1f360 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
1f370 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
1f380 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
1f390 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
1f3a0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
1f3b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1f3c0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
1f3d0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
1f3e0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
1f3f0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
1f400 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
1f410 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
1f420 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
1f430 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
1f440 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
1f450 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1f460 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
1f470 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
1f480 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
1f490 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
1f4a0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
1f4b0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
1f4c0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
1f4d0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
1f4e0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
1f4f0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
1f500 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
1f510 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
1f520 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
1f530 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1f540 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
1f550 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
1f560 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
1f570 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
1f580 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
1f590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
1f5a0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
1f5b0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
1f5c0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
1f5d0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
1f5e0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
1f5f0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f600 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
1f610 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1f620 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
1f630 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
1f640 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
1f650 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1f660 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1f670 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
1f680 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
1f690 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
1f6a0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
1f6b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f6c0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
1f6d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f6e0 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
1f6f0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
1f700 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
1f710 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
1f720 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
1f730 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
1f740 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
1f750 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
1f760 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
1f770 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
1f780 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
1f790 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
1f7a0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
1f7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f7c0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
1f7d0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
1f7e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
1f7f0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
1f800 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
1f810 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
1f820 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
1f830 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
1f840 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
1f850 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
1f860 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
1f870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f880 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
1f890 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
1f8a0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
1f8b0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
1f8c0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
1f8d0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
1f8e0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
1f8f0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
1f900 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
1f910 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
1f920 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
1f930 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
1f940 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
1f950 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
1f960 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
1f970 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
1f980 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
1f990 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
1f9a0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
1f9b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
1f9c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f9d0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
1f9e0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
1f9f0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
1fa00 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
1fa10 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
1fa20 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
1fa30 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
1fa40 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
1fa50 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
1fa60 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
1fa70 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
1fa80 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
1fa90 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
1faa0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
1fab0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
1fac0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1fad0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fae0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1faf0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
1fb00 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
1fb10 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
1fb20 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
1fb30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1fb40 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
1fb50 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
1fb60 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
1fb70 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
1fb80 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
1fb90 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
1fba0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
1fbb0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1fbc0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
1fbd0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1fbe0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32  ents:.** [H13202
1fbf0 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33  ] [H15304] [H153
1fc00 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31  06] [H15308] [H1
1fc10 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  5310].*/.int sql
1fc20 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
1fc30 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1fc40 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1fc50 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1fc60 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
1fc70 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
1fc80 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
1fc90 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
1fca0 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
1fcb0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
1fcc0 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  lt set..**.** Re
1fcd0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1fce0 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37 32 5d  H13771] [H13772]
1fcf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1fd00 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
1fd10 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1fd20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fd30 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
1fd40 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d  tatypes {H10265}
1fd50 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30   <S10110><S10120
1fd60 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  >.** KEYWORDS: S
1fd70 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
1fd80 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20   {H10266} Every 
1fd90 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
1fda0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
1fdb0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
1fdc0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
1fdd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
1fde0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
1fdf0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
1fe00 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
1fe10 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
1fe20 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
1fe30 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
1fe40 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
1fe50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1fe60 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
1fe70 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
1fe80 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
1fe90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
1fea0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
1feb0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
1fec0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
1fed0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
1fee0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
1fef0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
1ff00 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
1ff10 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
1ff20 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
1ff30 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
1ff40 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
1ff50 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
1ff60 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
1ff70 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
1ff80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
1ff90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1ffa0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
1ffb0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
1ffc0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
1ffd0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
1ffe0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
1fff0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
20000 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
20010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
20020 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
20030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
20040 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
20050 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
20060 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
20070 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c  Query {H13800} <
20080 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
20090 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
200a0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
200b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
200c0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
200d0 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
200e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
200f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20100 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
20110 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
20120 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
20130 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
20140 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
20150 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65  .  In every case
20160 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
20170 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
20180 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
20190 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
201a0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
201b0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
201c0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
201d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
201e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
201f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20200 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
20210 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
20220 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
20230 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
20240 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
20250 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
20260 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
20270 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
20280 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
20290 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
202a0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
202b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
202c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
202d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
202e0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
202f0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
20300 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
20310 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
20320 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
20330 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
20340 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
20350 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
20360 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
20370 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
20380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
20390 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
203a0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
203b0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
203c0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
203d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
203e0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
203f0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
20400 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
20410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
20420 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
20430 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20440 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
20450 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
20460 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
20470 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
20480 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
20490 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
204a0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
204b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
204c0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
204d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
204e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
204f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
20500 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
20510 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
20520 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
20530 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
20540 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
20550 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
20560 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
20570 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20580 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
20590 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
205a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
205b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
205c0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
205d0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
205e0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
205f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
20600 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
20610 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
20620 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
20630 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
20640 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
20650 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
20660 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
20670 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
20680 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
20690 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
206a0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
206b0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
206c0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
206d0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
206e0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
206f0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
20700 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
20710 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
20720 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
20730 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
20740 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
20750 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
20760 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
20770 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
20780 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
20790 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
207a0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
207b0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
207c0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
207d0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
207e0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
207f0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
20800 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
20810 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
20820 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20830 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
20840 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
20850 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
20860 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
20870 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
20880 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
20890 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
208a0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
208b0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
208c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
208d0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
208e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
208f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
20900 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
20910 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
20920 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
20930 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
20940 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
20950 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
20960 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
20970 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
20980 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
20990 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
209a0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
209b0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
209c0 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
209d0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
209e0 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
209f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
20a00 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
20a10 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
20a20 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
20a30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
20a40 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
20a50 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
20a60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
20a70 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
20a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
20a90 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
20aa0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
20ab0 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
20ac0 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
20ad0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
20ae0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
20af0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
20b00 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
20b10 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
20b20 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
20b30 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
20b40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
20b50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
20b60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
20b70 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
20b80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
20b90 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
20ba0 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
20bb0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
20bc0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20bd0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
20be0 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  -8..** The zero 
20bf0 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
20c00 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
20c10 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
20c20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
20c30 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20c40 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
20c50 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
20c60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20c70 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
20c80 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
20c90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20ca0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
20cb0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
20cc0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
20cd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
20ce0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
20cf0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
20d00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20d10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
20d20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
20d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
20d40 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
20d50 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
20d60 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
20d70 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
20d80 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
20d90 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
20da0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
20db0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
20dc0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
20dd0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20de0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
20df0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20e00 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
20e10 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
20e20 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
20e30 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
20e40 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
20e50 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
20e60 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
20e70 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
20e80 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
20e90 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
20ea0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
20eb0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
20ec0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
20ed0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
20ee0 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
20ef0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
20f00 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
20f10 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
20f20 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
20f30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
20f40 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
20f50 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
20f60 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
20f70 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
20f80 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
20f90 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
20fa0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
20fb0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
20fc0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
20fd0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20fe0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
20ff0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
21000 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
21010 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
21020 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
21030 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
21040 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
21050 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
21060 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
21070 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
21080 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
21090 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
210a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
210b0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
210c0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
210d0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
210e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
210f0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
21100 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
21110 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
21120 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
21130 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
21140 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
21150 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
21160 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
21170 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
21180 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
21190 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
211a0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
211b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
211c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
211d0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
211e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
211f0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
21200 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
21210 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
21220 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
21230 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
21240 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
21250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
21260 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
21270 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
21280 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
21290 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
212a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
212b0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
212c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
212d0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
212e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
212f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
21300 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
21310 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
21320 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
21330 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
21340 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
21350 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21360 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
21370 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
21380 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
21390 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
213a0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
213b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
213c0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
213d0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
213e0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
213f0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
21400 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
21410 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
21420 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
21430 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
21440 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
21450 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
21460 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
21470 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
21480 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
21490 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
214a0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
214b0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
214c0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
214d0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
214e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
214f0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
21500 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
21510 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
21520 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
21530 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
21540 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
21550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21560 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
21570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21580 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
21590 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
215a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
215b0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
215c0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
215d0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
215e0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
215f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
21600 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
21610 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
21620 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
21630 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
21640 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
21650 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
21660 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
21670 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
21680 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
21690 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
216a0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
216b0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
216c0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
216d0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
216e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
216f0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
21700 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
21710 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
21720 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
21730 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
21740 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
21750 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
21760 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
21770 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
21780 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
21790 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
217a0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
217b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
217c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
217d0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
217e0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
217f0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
21800 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
21810 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
21820 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
21830 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
21840 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
21850 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
21860 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
21870 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
21880 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
21890 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
218a0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
218b0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
218c0 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
218d0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
218e0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
218f0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
21900 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
21910 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
21920 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
21930 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
21940 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
21950 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
21960 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
21970 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
21980 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
21990 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
219a0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
219b0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
219c0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
219d0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
219e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
219f0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
21a00 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
21a10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
21a20 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
21a30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
21a40 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
21a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
21a60 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
21a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21a80 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
21a90 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
21aa0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
21ab0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
21ac0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
21ad0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
21ae0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
21af0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
21b00 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
21b10 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
21b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
21b30 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
21b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
21b50 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
21b60 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
21b70 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
21b80 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
21b90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
21ba0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
21bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21bc0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
21bd0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
21be0 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
21bf0 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
21c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21c10 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
21c20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
21c30 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
21c40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21c50 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
21c60 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
21c70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
21c80 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
21c90 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
21ca0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21cb0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
21cc0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
21cd0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
21ce0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
21cf0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
21d00 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
21d10 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
21d20 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
21d30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
21d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
21d50 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
21d60 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
21d70 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
21d80 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
21d90 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
21da0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
21db0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
21dc0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
21dd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
21de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
21df0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
21e00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
21e10 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
21e20 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
21e30 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
21e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
21e50 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
21e60 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
21e70 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
21e80 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
21e90 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
21ea0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
21eb0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
21ec0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
21ed0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
21ee0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
21ef0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
21f00 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
21f10 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
21f20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
21f30 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
21f40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
21f50 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  M]..**.** Requir
21f60 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38  ements:.** [H138
21f70 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 31  03] [H13806] [H1
21f80 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b  3809] [H13812] [
21f90 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38 5d  H13815] [H13818]
21fa0 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38 32   [H13821] [H1382
21fb0 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b  4].** [H13827] [
21fc0 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13830].*/.const
21fd0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21fe0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
21ff0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22000 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
22010 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
22020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22030 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
22040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22050 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22060 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
22070 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
22080 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
22090 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
220a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
220b0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
220c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
220d0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
220e0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
220f0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
22100 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22110 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
22120 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22130 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
22140 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22150 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
22160 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22170 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
22180 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
221a0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
221b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
221c0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
221d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
221e0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
221f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22200 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22210 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
22220 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
22230 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c  bject {H13300} <
22240 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S70300><S30100>.
22250 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22260 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
22270 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
22280 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
22290 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
222a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74  ..** If the stat
222b0 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
222c0 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
222d0 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
222e0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
222f0 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
22300 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74  urned. If execut
22310 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
22320 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
22330 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
22340 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
22350 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
22360 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
22370 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
22380 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
22390 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
223a0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
223b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
223c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66   statement].  If
223d0 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
223e0 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hine has not.** 
223f0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
22400 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
22410 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
22420 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
22430 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
22440 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71   error or an [sq
22450 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
22460 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a  | interrupt]..**
22470 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
22480 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
22490 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
224a0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
224b0 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
224c0 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
224d0 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
224e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
224f0 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
22500 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
22510 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
22520 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48  :.** [H11302] [H
22530 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  11304].*/.int sq
22540 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
22550 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22560 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
22570 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
22580 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
22590 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d   Object {H13330}
225a0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
225b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
225c0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
225d0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
225e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
225f0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
22600 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
22610 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
22620 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
22630 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
22640 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
22650 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
22660 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
22670 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
22680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22690 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
226a0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
226b0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
226c0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
226d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
226e0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
226f0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ndings..**.** {H
22700 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69  11332} The [sqli
22710 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
22720 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
22730 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22740 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
22750 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68        back to th
22760 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
22770 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
22780 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68  * {H11334} If th
22790 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
227a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
227b0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
227c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
227d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
227e0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
227f0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
22800 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
22810 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
22820 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
22830 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
22840 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
22850 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
22860 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
22870 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
22880 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
22890 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65   {H11336} If the
228a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
228b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
228c0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
228d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
228e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
228f0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
22900 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
22910 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22920 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
22930 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
22940 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
22950 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68  *.** {H11338} Th
22960 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
22970 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
22980 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
22990 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
229a0 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
229b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
229c0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
229d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
229e0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
229f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
22a00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22a10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22a20 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
22a30 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
22a40 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c  tions {H16100} <
22a50 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20200>.** KEYWO
22a60 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
22a70 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
22a80 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
22a90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
22aa0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
22ab0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
22ac0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
22ad0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
22ae0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  s}.**.** These t
22af0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
22b00 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
22b10 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
22b20 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
22b30 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
22b40 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
22b50 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
22b60 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
22b70 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
22b80 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
22b90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
22ba0 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
22bb0 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
22bc0 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
22bd0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
22be0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
22bf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
22c00 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
22c10 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
22c20 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
22c30 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
22c40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
22c50 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
22c60 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
22c70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
22c80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
22c90 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
22ca0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
22cb0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
22cc0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
22cd0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
22ce0 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
22cf0 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73  gle program uses
22d00 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
22d10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
22d20 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  ction internally
22d30 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74  , then SQL funct
22d40 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
22d50 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20  ed individually 
22d60 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  to.** each datab
22d70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
22d80 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
22d90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22da0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
22db0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
22dc0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
22dd0 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c  edefined.  The l
22de0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
22df0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
22e00 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
22e10 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a  sive of.** the z
22e20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
22e30 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
22e40 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
22e50 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
22e60 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
22e70 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
22e80 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
22e90 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
22ea0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
22eb0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
22ec0 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74  ERROR] being ret
22ed0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
22ee0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22ef0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
22f00 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
22f10 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
22f20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
22f30 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
22f40 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d  s. If this param
22f50 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
22f60 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
22f70 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
22f80 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
22f90 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
22fa0 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
22fb0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
22fc0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
22fd0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
22fe0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
22ff0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
23000 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
23010 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
23020 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
23030 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
23040 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
23050 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
23060 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
23070 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
23080 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
23090 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
230a0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
230b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
230c0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
230d0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
230e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
230f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
23100 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
23110 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
23120 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
23130 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
23140 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
23150 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
23160 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
23170 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
23180 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
23190 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64  .  It is allowed
231a0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
231b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
231c0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
231d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
231e0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
231f0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
23200 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
23210 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
23220 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
23230 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d  xtRep..** When m
23240 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
23250 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
23260 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
23270 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
23280 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
23290 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
232a0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
232b0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
232c0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
232d0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
232e0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
232f0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
23300 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
23310 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
23320 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
23330 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
23340 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
23350 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
23360 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   The fifth param
23370 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
23380 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
23390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
233a0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
233b0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
233c0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
233d0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
233e0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
233f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
23400 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
23410 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
23420 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
23430 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
23440 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
23450 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
23460 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
23470 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
23480 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
23490 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
234a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
234b0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
234c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
234d0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
234e0 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
234f0 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
23500 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
23510 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
23520 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
23530 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
23540 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
23550 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
23560 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
23570 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
23580 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
23590 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
235a0 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
235b0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
235c0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
235d0 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
235e0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20   three function 
235f0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
23600 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
23610 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
23620 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
23630 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
23640 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
23650 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
23660 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
23670 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
23680 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
23690 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
236a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
236b0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
236c0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
236d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
236e0 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
236f0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
23700 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
23710 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
23720 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e  sed.  A function
23730 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23740 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
23750 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
23760 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
23770 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
23780 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
23790 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
237a0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
237b0 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
237c0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
237d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
237e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
237f0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
23800 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
23810 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
23820 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
23830 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
23840 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63  ent.  .** A func
23850 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
23860 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
23870 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
23880 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
23890 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
238a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
238b0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
238c0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
238d0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
238e0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
238f0 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69  6..**.** Built-i
23900 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
23910 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
23920 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
23930 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
23940 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ns..** The first
23950 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
23960 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69  ined function wi
23970 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20  th a given name 
23980 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a  overrides all.**
23990 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   built-in functi
239a0 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ons in the same 
239b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
239c0 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73  tion] with the s
239d0 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62  ame name..** Sub
239e0 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74  sequent applicat
239f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
23a00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
23a10 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72  e name only over
23a20 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61  ride .** prior a
23a30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23a40 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ed functions tha
23a50 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d  t are an exact m
23a60 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20  atch for the.** 
23a70 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
23a80 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72  ters and preferr
23a90 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  ed encoding..**.
23aa0 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** An applicatio
23ab0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
23ac0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
23ad0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
23ae0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
23af0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
23b00 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
23b10 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
23b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23b30 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
23b40 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
23b50 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
23b60 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
23b70 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
23b80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
23b90 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
23ba0 31 30 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48  103] [H16106] [H
23bb0 31 36 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20  16109] [H16112] 
23bc0 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31  [H16118] [H16121
23bd0 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48  ] [H16127].** [H
23be0 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20  16130] [H16133] 
23bf0 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39  [H16136] [H16139
23c00 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e  ] [H16142].*/.in
23c10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
23c20 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
23c30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
23c40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
23c50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
23c60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
23c70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
23c80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
23c90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23ca0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23cb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
23cc0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
23cd0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23ce0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23cf0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
23d00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
23d10 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
23d20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23d30 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
23d40 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
23d50 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
23d60 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
23d70 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
23d80 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
23d90 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
23da0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
23db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
23dc0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
23dd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
23de0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
23df0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
23e00 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
23e10 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
23e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
23e30 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
23e40 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
23e50 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
23e60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
23e70 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
23e80 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
23e90 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
23ea0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
23eb0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
23ec0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
23ed0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
23ee0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
23ef0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
23f00 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
23f10 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
23f20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
23f30 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
23f40 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
23f50 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
23f60 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
23f70 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
23f80 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
23f90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23fa0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
23fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
23fc0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
23fd0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
23fe0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
23ff0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24000 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
24010 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
24020 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
24030 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
24040 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
24050 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
24060 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
24070 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
24080 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
24090 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
240a0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
240b0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
240c0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
240d0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
240e0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
240f0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
24100 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
24110 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
24120 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
24130 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
24140 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
24150 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
24160 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
24170 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
24180 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
24190 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
241a0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
241b0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
241c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
241d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
241e0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
241f0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
24200 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
24210 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
24220 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
24230 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
24240 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
24250 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
24260 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
24270 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
24280 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
24290 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
242a0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
242b0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
242c0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
242d0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
242e0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
242f0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
24300 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
24310 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
24320 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
24330 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24340 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
24350 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
24360 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32  s {H15100} <S202
24370 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00>.**.** The C-
24380 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
24390 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
243a0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
243b0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
243c0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
243d0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
243e0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
243f0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
24400 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
24410 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
24420 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
24430 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
24440 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
24450 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
24460 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
24470 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24480 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
24490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
244a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
244b0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
244c0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
244d0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
244e0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
244f0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
24500 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
24510 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
24520 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
24530 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
24540 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24550 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
24560 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
24570 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24580 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
24590 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
245a0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
245b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
245c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
245d0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
245e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
245f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
24600 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
24610 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
24620 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
24630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24640 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
24650 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
24660 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
24670 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24680 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
24690 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
246a0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
246b0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
246c0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
246d0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
246e0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
246f0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
24700 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
24710 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
24720 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
24730 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
24740 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
24750 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
24760 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
24770 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
24780 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
24790 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
247a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
247b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
247c0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
247d0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
247e0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
247f0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
24800 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
24810 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
24820 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24830 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
24840 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
24850 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
24860 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
24870 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
24880 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
24890 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
248a0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vely..**.** The 
248b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
248c0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
248d0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
248e0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
248f0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
24900 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
24910 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
24920 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
24930 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
24940 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
24950 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
24960 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
24970 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
24980 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
24990 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
249a0 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
249b0 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
249c0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
249d0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
249e0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
249f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
24a00 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
24a10 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
24a20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
24a30 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
24a40 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
24a50 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
24a60 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
24a70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
24a80 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
24a90 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
24aa0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
24ab0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
24ac0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
24ad0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
24ae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
24af0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
24b00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24b10 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
24b20 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
24b30 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
24b40 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
24b50 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
24b60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24b70 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
24b80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
24b90 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
24ba0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
24bb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
24bc0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
24bd0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
24be0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
24bf0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
24c00 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
24c10 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
24c20 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
24c30 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
24c40 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30  ments:.** [H1510
24c50 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35  3] [H15106] [H15
24c60 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48  109] [H15112] [H
24c70 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20  15115] [H15118] 
24c80 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34  [H15121] [H15124
24c90 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48  ].** [H15127] [H
24ca0 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20  15130] [H15133] 
24cb0 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73  [H15136].*/.cons
24cc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24cd0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
24ce0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
24cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
24d00 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
24d10 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24d20 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
24d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24d40 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
24d50 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
24d60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
24d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
24d80 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
24d90 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
24da0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
24db0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
24dc0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
24dd0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
24de0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
24df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
24e00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
24e10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
24e20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24e30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24e40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
24e50 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
24e60 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
24e70 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
24e80 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
24e90 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
24ea0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
24eb0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24ec0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
24ed0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
24ee0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
24ef0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24f00 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
24f10 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
24f20 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
24f30 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
24f40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24f50 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
24f60 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
24f70 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
24f80 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
24f90 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
24fa0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
24fb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
24fc0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
24fd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
24fe0 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
24ff0 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
25000 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
25010 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
25020 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
25030 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
25040 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
25050 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
25060 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
25070 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
25080 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
25090 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
250a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
250b0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
250c0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
250d0 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
250e0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
250f0 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
25100 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
25110 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
25120 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
25130 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
25140 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
25150 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
25160 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
25170 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
25180 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
25190 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
251a0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
251b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
251c0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
251d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
251e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
251f0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
25200 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
25210 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
25220 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
25230 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
25240 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
25250 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
25260 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
25270 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
25280 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
25290 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
252a0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
252b0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
252c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
252d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
252e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
252f0 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31  11] [H16213] [H1
25300 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a  6215] [H16217].*
25310 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
25320 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
25330 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
25340 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
25350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25360 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
25370 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34  Functions {H1624
25380 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
25390 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
253a0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
253b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
253c0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
253d0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
253e0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
253f0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
25400 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
25410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
25420 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
25430 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
25440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25450 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
25460 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
25470 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
25480 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
25490 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
254a0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
254b0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
254c0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
254d0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
254e0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
254f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
25500 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
25510 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
25520 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
25530 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  43].*/.void *sql
25540 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
25550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
25560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25570 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
25580 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
25590 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
255a0 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
255b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
255c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
255d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
255e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
255f0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
25600 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
25610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
25620 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
25630 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
25640 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25650 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
25660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25670 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
25680 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
25690 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
256a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
256b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
256c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ion..**.** Requi
256d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
256e0 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  253].*/.sqlite3 
256f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
25700 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
25710 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
25720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
25730 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
25740 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20  y Data {H16270} 
25750 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
25760 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
25770 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
25780 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
25790 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
257a0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
257b0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
257c0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
257d0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
257e0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
257f0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
25800 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
25810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
25820 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
25830 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
25840 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
25850 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
25860 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
25870 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
25880 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
25890 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
258a0 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
258b0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
258c0 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
258d0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
258e0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
258f0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
25900 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
25910 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
25920 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
25930 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
25940 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
25950 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
25960 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
25970 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
25980 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
25990 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
259a0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
259b0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
259c0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
259d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
259e0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
259f0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
25a00 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
25a10 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
25a20 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
25a30 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
25a40 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
25a50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
25a60 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
25a70 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
25a80 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
25a90 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
25aa0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
25ab0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
25ac0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
25ad0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25ae0 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74  ction. If no met
25af0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
25b00 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
25b10 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
25b20 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
25b30 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
25b40 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
25b50 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
25b60 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
25b70 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
25b80 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
25b90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
25ba0 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
25bb0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
25bc0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
25bd0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
25be0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
25bf0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
25c00 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
25c10 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
25c20 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
25c30 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
25c40 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
25c50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
25c60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
25c70 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
25c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25c90 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
25ca0 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
25cb0 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
25cc0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
25cd0 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74  troyed..** If it
25ce0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
25cf0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
25d00 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
25d10 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
25d20 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
25d30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25d40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
25d50 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
25d60 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
25d70 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
25d80 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
25d90 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
25da0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
25db0 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
25dc0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
25dd0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
25de0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
25df0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
25e00 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
25e10 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
25e20 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
25e30 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
25e40 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
25e50 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
25e60 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
25e70 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
25e80 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
25e90 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
25ea0 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
25eb0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
25ec0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
25ed0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
25ee0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
25ef0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
25f00 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
25f10 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
25f20 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
25f30 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
25f40 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
25f50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
25f60 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
25f70 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
25f80 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
25f90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
25fa0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
25fb0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
25fc0 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32  * [H16272] [H162
25fd0 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31  74] [H16276] [H1
25fe0 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b  6277] [H16278] [
25ff0 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20  H16279].*/.void 
26000 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
26010 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
26020 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
26030 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
26040 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
26050 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
26060 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
26070 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
26080 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
26090 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
260a0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
260b0 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
260c0 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  80} <S30100>.**.
260d0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
260e0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
260f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
26100 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
26110 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
26120 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
26130 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
26140 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
26150 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
26160 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
26170 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
26180 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
26190 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
261a0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
261b0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
261c0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
261d0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
261e0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
261f0 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
26200 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
26210 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
26220 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
26230 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
26240 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
26250 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
26260 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
26270 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
26280 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
26290 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
262a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
262b0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
262c0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
262d0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
262e0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
262f0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
26300 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
26310 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
26320 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
26330 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
26340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
26350 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
26360 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
26370 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
26380 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
26390 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
263a0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
263b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
263c0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
263d0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
263e0 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
263f0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
26400 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26410 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
26420 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
26430 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
26440 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
26450 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
26460 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
26470 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26480 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
26490 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
264a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
264b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
264c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
264d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
264e0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
264f0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
26500 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
26510 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
26520 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
26530 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
26540 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
26550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26560 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
26570 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
26580 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
26590 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
265a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
265b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
265c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
265d0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
265e0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
265f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
26600 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26610 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
26620 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
26630 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
26640 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
26650 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
26660 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
26670 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
26680 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
26690 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
266a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
266b0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
266c0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
266d0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
266e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
266f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
26700 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
26710 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
26720 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
26730 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
26740 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
26750 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
26760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26770 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
26780 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
26790 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
267a0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
267b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
267c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
267d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
267e0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
267f0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
26800 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
26810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26820 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
26830 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
26840 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
26850 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
26860 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
26870 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
26880 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
26890 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
268a0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
268b0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
268c0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
268d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
268e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
268f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
26900 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
26910 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
26920 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
26930 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
26940 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
26950 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
26960 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
26970 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
26980 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
26990 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
269a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
269b0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
269c0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
269d0 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
269e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
269f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
26a00 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
26a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26a20 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
26a30 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
26a40 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
26a50 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
26a60 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
26a70 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
26a80 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
26a90 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
26aa0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26ab0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
26ac0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
26ad0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
26ae0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
26af0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
26b00 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
26b10 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
26b20 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
26b30 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
26b40 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
26b50 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
26b60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
26b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
26b80 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
26b90 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
26ba0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
26bb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
26bc0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
26bd0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
26be0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
26bf0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
26c00 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
26c10 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
26c20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
26c30 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
26c40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26c50 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
26c60 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
26c70 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
26c80 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
26c90 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
26ca0 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
26cb0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
26cc0 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
26cd0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
26ce0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
26cf0 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
26d00 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
26d10 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
26d20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
26d30 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
26d40 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
26d50 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
26d60 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
26d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
26d80 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
26d90 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
26da0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
26db0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
26dc0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
26dd0 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
26de0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
26df0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
26e00 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
26e10 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
26e20 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
26e30 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
26e40 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
26e50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
26e60 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
26e70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
26e80 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
26e90 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
26ea0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
26eb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26ec0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
26ed0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
26ee0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
26ef0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
26f00 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
26f10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
26f20 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
26f30 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
26f40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
26f50 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
26f60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26f70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
26f80 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
26f90 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
26fa0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
26fb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
26fc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26fd0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
26fe0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
26ff0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
27000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27010 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27020 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
27030 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
27040 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
27050 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27060 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
27070 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
27080 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
27090 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
270a0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
270b0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
270c0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
270d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
270e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
270f0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
27100 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
27110 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
27120 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
27130 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
27140 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
27150 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
27160 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
27170 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
27180 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
27190 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
271a0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
271b0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
271c0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
271d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
271e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
271f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
27200 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
27210 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
27220 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
27230 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27240 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
27250 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
27260 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
27270 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
27280 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
27290 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
272a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
272b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
272c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
272d0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
272e0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
272f0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
27300 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
27310 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
27320 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
27330 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
27340 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
27350 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27360 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
27370 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
27380 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
27390 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
273a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
273b0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
273c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
273d0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
273e0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
273f0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
27400 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
27410 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
27420 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
27430 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
27440 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
27450 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
27460 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
27470 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
27480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27490 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
274a0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
274b0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
274c0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
274d0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
274e0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
274f0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
27500 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
27510 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
27520 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
27530 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
27540 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27550 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
27560 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
27570 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
27580 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
27590 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
275a0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
275b0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
275c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
275d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
275e0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
275f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
27600 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
27610 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
27620 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
27630 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
27640 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
27650 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
27660 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
27670 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
27680 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
27690 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
276a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
276b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
276c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
276d0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
276e0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
276f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27700 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
27710 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
27720 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27730 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
27740 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
27750 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
27760 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
27770 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
27780 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
27790 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
277a0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
277b0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
277c0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
277d0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
277e0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
277f0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
27800 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
27810 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
27820 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
27830 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
27840 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27850 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
27860 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
27870 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
27880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27890 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
278a0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
278b0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
278c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
278d0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
278e0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
278f0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
27900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27910 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
27920 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
27930 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
27940 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
27950 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
27960 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27970 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
27980 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
27990 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
279a0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
279b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
279c0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
279d0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d  nts:.** [H16403]
279e0 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30   [H16406] [H1640
279f0 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36  9] [H16412] [H16
27a00 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48  415] [H16418] [H
27a10 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a  16421] [H16424].
27a20 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36  ** [H16427] [H16
27a30 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48  430] [H16433] [H
27a40 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20  16436] [H16439] 
27a50 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35  [H16442] [H16445
27a60 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48  ] [H16448].** [H
27a70 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20  16451] [H16454] 
27a80 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30  [H16457] [H16460
27a90 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f  ] [H16463].*/.vo
27aa0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27ab0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
27ac0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
27ad0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27ae0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27b00 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
27b10 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
27b20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27b30 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
27b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27b50 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
27b60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27b70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
27b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
27b90 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
27ba0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27bb0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
27bc0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
27bd0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
27be0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
27bf0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
27c00 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
27c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27c20 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
27c30 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
27c40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27c50 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
27c60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
27c70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27c80 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
27c90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
27ca0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
27cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27cc0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
27cd0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
27ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27cf0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27d00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
27d10 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27d20 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27d30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27d40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27d50 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
27d60 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27d70 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
27d80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
27d90 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
27da0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
27db0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
27dc0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
27dd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
27de0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
27df0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
27e00 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
27e10 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
27e20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
27e30 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
27e40 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
27e50 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
27e60 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
27e70 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
27e80 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
27e90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
27ea0 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
27eb0 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
27ec0 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
27ed0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
27ee0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
27ef0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
27f00 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
27f10 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
27f20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
27f30 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
27f40 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
27f50 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
27f60 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
27f70 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
27f80 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
27f90 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
27fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27fb0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
27fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27fd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
27fe0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
27ff0 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
28000 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28010 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
28020 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
28030 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
28040 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
28050 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
28060 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28070 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
28080 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
28090 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
280a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
280b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
280c0 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
280d0 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
280e0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
280f0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
28100 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
28110 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
28120 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
28130 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
28140 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
28150 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
28160 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
28170 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
28180 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
28190 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
281a0 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
281b0 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
281c0 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
281d0 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
281e0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
281f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
28200 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
28210 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
28220 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
28230 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
28240 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
28250 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
28260 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
28270 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
28280 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
28290 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
282a0 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
282b0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
282c0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
282d0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
282e0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
282f0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
28300 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
28310 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
28320 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
28330 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
28340 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
28350 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
28360 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
28370 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
28380 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
28390 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
283a0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
283b0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
283c0 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
283d0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
283e0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
283f0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
28400 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28410 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
28420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28430 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
28440 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
28450 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
28460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
28470 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
28480 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
28490 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
284a0 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
284b0 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
284c0 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
284d0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
284e0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
284f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28500 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
28510 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
28520 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
28530 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
28540 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
28550 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
28560 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
28570 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
28580 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
28590 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
285a0 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
285b0 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
285c0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
285d0 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
285e0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
285f0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
28600 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
28610 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
28620 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
28630 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
28640 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
28650 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
28660 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
28670 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
28680 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
28690 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
286a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
286b0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
286c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
286d0 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
286e0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
286f0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
28700 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
28710 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
28720 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28730 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
28740 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
28750 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
28760 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
28770 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
28780 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
28790 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
287a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
287b0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
287c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
287d0 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
287e0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
287f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28800 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
28810 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
28820 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
28830 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
28840 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
28850 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36  ements:.** [H166
28860 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31  03] [H16604] [H1
28870 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b  6606] [H16609] [
28880 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d  H16612] [H16615]
28890 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32   [H16618] [H1662
288a0 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b  1].** [H16624] [
288b0 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d  H16627] [H16630]
288c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
288d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
288e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
288f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
28900 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
28910 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
28920 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
28930 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28940 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
28950 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
28960 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28970 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
28980 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
28990 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
289a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
289b0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
289c0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
289d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
289e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
289f0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
28a00 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
28a10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28a20 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
28a30 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
28a40 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
28a50 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
28a60 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
28a70 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
28a80 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
28a90 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
28aa0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
28ab0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
28ac0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
28ad0 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
28ae0 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
28af0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
28b00 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
28b10 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
28b20 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
28b30 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
28b40 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
28b50 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
28b60 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
28b70 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
28b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
28b90 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
28ba0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
28bb0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
28bc0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
28bd0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
28be0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
28bf0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
28c00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
28c10 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
28c20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
28c30 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
28c40 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
28c50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
28c60 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
28c70 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
28c80 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
28c90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
28ca0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
28cb0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
28cc0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
28cd0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
28ce0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
28cf0 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
28d00 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
28d10 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
28d20 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
28d30 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
28d40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
28d50 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
28d60 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
28d70 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
28d80 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28d90 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
28da0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28db0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
28dc0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28dd0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
28de0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28df0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28e00 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
28e10 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
28e20 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
28e30 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
28e40 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
28e50 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
28e60 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
28e70 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
28e80 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
28e90 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
28ea0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
28eb0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
28ec0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
28ed0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
28ee0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
28ef0 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
28f00 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
28f10 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
28f20 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
28f30 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
28f40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
28f50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28f60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
28f70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
28f80 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
28f90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28fa0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
28fb0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
28fc0 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37  * [H16702] [H167
28fd0 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a  04] [H16706].*/.
28fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
28ff0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
29000 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
29010 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
29020 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
29030 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
29040 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
29050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
29060 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
29070 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
29080 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
29090 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
290a0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
290b0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
290c0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
290d0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
290e0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
290f0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
29100 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
29110 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
29120 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
29130 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
29140 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
29150 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
29160 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
29170 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
29180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29190 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
291a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
291b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
291c0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
291d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
291e0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
291f0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
29200 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
29210 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
29220 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
29230 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
29240 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
29250 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
29260 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
29270 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
29280 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
29290 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
292a0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
292b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
292c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
292d0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
292e0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
292f0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
29300 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
29310 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
29320 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29340 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
29350 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
29360 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
29370 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
29380 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
29390 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
293a0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
293b0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
293c0 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
293d0 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
293e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
293f0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
29400 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
29410 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
29420 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
29430 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
29440 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
29450 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
29460 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
29470 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
29480 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
29490 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
294a0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
294b0 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
294c0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
294d0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
294e0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
294f0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
29500 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
29510 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
29520 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
29530 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
29540 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
29550 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
29560 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
29570 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
29580 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
29590 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
295a0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
295b0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
295c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
295d0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
295e0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
295f0 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31  ts: [H10533] [H1
29600 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  0536].*/.int sql
29610 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
29620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29630 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
29640 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
29650 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31  porary Files {H1
29660 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0310} <S20000>.*
29670 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
29680 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
29690 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
296a0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
296b0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
296c0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
296d0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
296e0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
296f0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
29700 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
29710 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
29720 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
29730 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
29740 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
29750 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
29760 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
29770 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
29780 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
29790 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
297a0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
297b0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
297c0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
297d0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
297e0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
297f0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
29800 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
29810 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
29820 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
29830 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
29840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
29850 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
29860 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
29870 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
29880 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
29890 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
298a0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
298b0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
298c0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
298d0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
298e0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
298f0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
29900 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
29910 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
29920 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
29930 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
29940 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
29950 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f  **.** The [temp_
29960 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
29970 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
29980 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
29990 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
299a0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
299b0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
299c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
299d0 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  c].  Furthermore
299e0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
299f0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
29a00 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
29a10 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
29a20 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
29a30 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
29a40 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
29a50 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
29a60 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
29a70 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
29a80 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
29a90 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
29aa0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
29ab0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
29ac0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
29ad0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
29ae0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
29af0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
29b00 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
29b10 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
29b20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
29b30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
29b40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
29b50 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
29b60 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
29b70 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
29b80 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
29b90 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
29ba0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
29bb0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
29bc0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
29bd0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
29be0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
29bf0 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
29c00 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
29c10 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
29c20 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
29c30 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
29c40 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
29c50 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
29c60 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
29c70 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
29c80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29c90 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
29ca0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
29cb0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29cc0 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
29cd0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
29ce0 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
29cf0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
29d00 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
29d10 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
29d20 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
29d30 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
29d40 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
29d50 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
29d60 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
29d70 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
29d80 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
29d90 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
29da0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
29db0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
29dc0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
29dd0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
29de0 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
29df0 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
29e00 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
29e10 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
29e20 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
29e30 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
29e40 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
29e50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
29e60 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
29e70 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
29e80 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
29e90 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
29ea0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
29eb0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
29ec0 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
29ed0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
29ee0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
29ef0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
29f00 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
29f10 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
29f20 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
29f30 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
29f40 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
29f50 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
29f60 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
29f70 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
29f80 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
29f90 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b  2931] [H12932] [
29fa0 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d  H12933] [H12934]
29fb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29fc0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
29fd0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
29fe0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
29ff0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2a000 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2a010 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
2a020 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  120} <S60600>.**
2a030 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a040 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2a050 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2a060 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a070 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2a080 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
2a090 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a0a0 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64  belongs.  The [d
2a0b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a0c0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2a0d0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2a0e0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2a0f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2a100 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20  ction] that was 
2a110 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a120 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
2a130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a140 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
2a150 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
2a160 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
2a170 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2a180 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2a190 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65   place..**.** Re
2a1a0 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
2a1b0 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  123].*/.sqlite3 
2a1c0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
2a1d0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2a1e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a1f0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
2a200 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2a210 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53  ment {H13140} <S
2a220 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60600>.**.** Thi
2a230 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2a240 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a250 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
2a260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2a270 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
2a280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2a290 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a2a0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
2a2b0 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
2a2c0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
2a2d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2a2e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2a2f0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
2a300 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
2a310 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
2a320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a330 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70  on pDb.  If no p
2a340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a350 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2a360 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2a370 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2a380 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2a390 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2a3a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a3b0 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2a3c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a3d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2a3e0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2a3f0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2a400 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2a410 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2a420 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2a430 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2a440 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2a450 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31  : [H13143] [H131
2a460 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31  46] [H13149] [H1
2a470 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3152].*/.sqlite3
2a480 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2a490 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2a4a0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2a4b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a4c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a4d0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2a4e0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2a4f0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
2a500 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
2a510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
2a520 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
2a530 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2a540 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2a550 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2a560 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2a570 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
2a580 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
2a590 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  d]..** Any callb
2a5a0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2a5b0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2a5c0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2a5d0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2a5e0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2a5f0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2a600 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
2a610 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2a620 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2a630 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2a640 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2a650 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2a660 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2a670 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2a680 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2a690 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  ]..** Any callba
2a6a0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2a6b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2a6c0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2a6d0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2a6e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2a6f0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2a700 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72  dden..** The pAr
2a710 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2a720 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2a730 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2a740 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
2a750 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
2a760 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
2a770 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
2a780 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
2a790 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2a7a0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
2a7b0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
2a7c0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
2a7d0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2a7e0 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
2a7f0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2a800 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
2a810 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
2a820 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2a830 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2a840 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2a850 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2a860 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2a870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a880 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2a890 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
2a8a0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2a8b0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2a8c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2a8d0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2a8e0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2a8f0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2a900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2a910 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2a920 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
2a930 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
2a940 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
2a950 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
2a960 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2a970 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2a990 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2a9a0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2a9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2a9c0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2a9d0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2a9e0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2a9f0 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
2aa00 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2aa10 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2aa20 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
2aa30 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2aa40 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
2aa50 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
2aa60 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
2aa70 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
2aa80 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
2aa90 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 49 66  ue normally.  If
2aaa0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2aab0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2aac0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2aad0 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2aae0 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2aaf0 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72  LBACK]..** The r
2ab00 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2ab10 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2ab20 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2ab30 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2ab40 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2ab50 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2ab60 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2ab70 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2ab80 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2ab90 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
2aba0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
2abb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
2abc0 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
2abd0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2abe0 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
2abf0 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
2ac00 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
2ac10 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
2ac20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
2ac30 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
2ac40 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
2ac50 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
2ac60 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2ac70 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2ac80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2ac90 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2aca0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2acb0 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
2acc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2acd0 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
2ace0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2acf0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2ad00 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2ad10 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
2ad20 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
2ad30 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
2ad40 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
2ad50 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
2ad60 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
2ad70 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2ad80 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2ad90 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2ada0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  face..**.** Requ
2adb0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
2adc0 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b  2951] [H12952] [
2add0 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d  H12953] [H12954]
2ade0 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31   [H12955].** [H1
2adf0 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b  2961] [H12962] [
2ae00 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d  H12963] [H12964]
2ae10 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ae20 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2ae30 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2ae40 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2ae50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2ae60 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2ae70 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2ae80 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2ae90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2aea0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2aeb0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2aec0 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34  s {H12970} <S604
2aed0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2aee0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2aef0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2af00 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2af10 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2af20 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2af30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2af40 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2af50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2af60 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2af70 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2af80 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2af90 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2afa0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2afb0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2afc0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2afd0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2afe0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2aff0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2b000 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2b010 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2b020 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2b030 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2b040 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2b050 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2b060 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2b070 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68  r deleted..** Th
2b080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b090 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2b0a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2b0b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2b0c0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
2b0d0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
2b0e0 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
2b0f0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2b100 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b110 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2b120 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
2b130 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
2b140 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2b150 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2b160 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2b170 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
2b180 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
2b190 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2b1a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2b1b0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2b1c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2b1d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2b1e0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2b1f0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2b200 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
2b210 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2b220 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2b230 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
2b240 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
2b250 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2b260 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2b270 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2b280 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2b290 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2b2a0 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2b2b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2b2c0 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2b2d0 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2b2e0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2b2f0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2b300 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a  te_sequence)..**
2b310 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 72 65  .** In the curre
2b320 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2b330 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2b340 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2b350 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2b360 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2b370 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2b380 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2b390 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2b3a0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2b3b0 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 65 20  se.  Nor is the 
2b3c0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2b3d0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2b3e0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2b3f0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2b400 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2b410 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2b420 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2b430 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2b440 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2b450 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2b460 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2b470 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2b480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b490 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2b4a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2b4b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2b4c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b4d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2b4e0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2b4f0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2b500 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2b510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b520 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2b530 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2b540 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2b550 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b560 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2b570 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2b580 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2b590 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2b5a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b5b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2b5c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2b5d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2b5e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2b5f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2b600 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2b610 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2b620 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2b630 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
2b640 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2b650 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
2b660 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
2b670 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
2b680 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
2b690 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2b6a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
2b6b0 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
2b6c0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2b6d0 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
2b6e0 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  rfaces..**.** Re
2b6f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
2b700 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33 5d  H12971] [H12973]
2b710 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39 37   [H12975] [H1297
2b720 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31 32  7] [H12979] [H12
2b730 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48  981] [H12983] [H
2b740 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12986].*/.void *
2b750 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2b760 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
2b770 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2b780 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
2b790 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
2b7a0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2b7b0 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
2b7c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2b7d0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2b7e0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2b7f0 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30  he {H10330} <S30
2b800 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  900>.** KEYWORDS
2b810 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
2b820 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b830 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
2b840 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
2b850 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
2b860 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
2b870 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
2b880 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
2b890 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b8a0 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
2b8b0 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
2b8c0 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
2b8d0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2b8e0 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2b8f0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
2b900 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
2b910 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
2b920 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68  ..**.** Cache sh
2b930 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2b940 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2b950 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2b960 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2b970 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2b980 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2b990 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2b9a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2b9b0 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2b9c0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2b9d0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2b9e0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2b9f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
2ba00 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
2ba10 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
2ba20 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
2ba30 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
2ba40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2ba50 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2ba60 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2ba70 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
2ba80 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
2ba90 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
2baa0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2bab0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
2bac0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
2bad0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
2bae0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
2baf0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
2bb00 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
2bb10 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
2bb20 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
2bb30 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
2bb40 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
2bb50 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
2bb60 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2bb70 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
2bb80 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
2bb90 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
2bba0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
2bbb0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
2bbc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2bbd0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
2bbe0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
2bbf0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2bc00 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
2bc10 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
2bc20 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2bc30 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
2bc40 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
2bc50 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2bc60 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
2bc70 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
2bc80 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
2bc90 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
2bca0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
2bcb0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
2bcc0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
2bcd0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
2bce0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
2bcf0 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
2bd00 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
2bd10 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a  Cache Mode].**.*
2bd20 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2bd30 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36  [H10331] [H10336
2bd40 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33  ] [H10337] [H103
2bd50 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  39].*/.int sqlit
2bd60 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
2bd70 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
2bd80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
2bd90 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
2bda0 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34  ap Memory {H1734
2bdb0 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a  0} <S30220>.**.*
2bdc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2bdd0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2bde0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2bdf0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2be00 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2be10 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2be20 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2be30 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2be40 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2be50 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2be60 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
2be70 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
2be80 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
2be90 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
2bea0 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
2beb0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
2bec0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2bed0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c  ..** sqlite3_rel
2bee0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
2bef0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2bf00 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
2bf10 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69  ly freed,.** whi
2bf20 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
2bf30 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68   or less than th
2bf40 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
2bf50 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
2bf60 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d  ements: [H17341]
2bf70 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74   [H17342].*/.int
2bf80 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2bf90 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
2bfa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2bfb0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
2bfc0 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33   Heap Size {H173
2bfd0 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a  50} <S30220>.**.
2bfe0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2bff0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
2c000 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65   interface place
2c010 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
2c020 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  .** on the amoun
2c030 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
2c040 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
2c050 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
2c060 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  ..** If an inter
2c070 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
2c080 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74  s requested that
2c090 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2c0a0 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c  e.** soft heap l
2c0b0 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
2c0c0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2c0d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20   is invoked one 
2c0e0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73  or.** more times
2c0f0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
2c100 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
2c110 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  e allocation is 
2c120 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a  performed..**.**
2c130 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
2c140 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
2c150 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33  ause if [sqlite3
2c160 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2c170 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65  )].** cannot fre
2c180 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  e sufficient mem
2c190 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74  ory to prevent t
2c1a0 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65  he limit from be
2c1b0 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a  ing exceeded,.**
2c1c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61   the memory is a
2c1d0 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20  llocated anyway 
2c1e0 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
2c1f0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
2c200 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61  ds..**.** A nega
2c210 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c  tive or zero val
2c220 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74  ue for N means t
2c230 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
2c240 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2c250 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c260 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2c270 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  ] will only be c
2c280 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
2c290 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  y is exhausted..
2c2a0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
2c2b0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
2c2c0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
2c2d0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
2c2e0 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
2c2f0 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
2c300 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2c310 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74  mit..** But if t
2c320 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2c330 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e  it cannot be hon
2c340 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20  ored, execution 
2c350 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65  will.** continue
2c360 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f   without error o
2c370 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20  r notification. 
2c380 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65   This is why the
2c390 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c   limit is.** cal
2c3a0 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  led a "soft" lim
2c3b0 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73  it.  It is advis
2c3c0 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
2c3d0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
2c3e0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
2c3f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
2c400 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65   constrained the
2c410 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
2c420 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  ated by a single
2c430 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61   thread - the sa
2c440 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2c450 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  ch this routine.
2c460 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e  ** runs.  Beginn
2c470 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
2c480 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
2c490 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2c4a0 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64  it is.** applied
2c4b0 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   to all threads.
2c4c0 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69   The value speci
2c4d0 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66  fied for the sof
2c4e0 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20  t heap limit.** 
2c4f0 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e  is an upper boun
2c500 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d  d on the total m
2c510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c520 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73   for all threads
2c530 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  . In.** version 
2c540 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e  3.5.0 there is n
2c550 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20  o mechanism for 
2c560 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61  limiting the hea
2c570 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69  p usage for.** i
2c580 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64  ndividual thread
2c590 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
2c5a0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35  ments:.** [H1635
2c5b0 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31 36  1] [H16352] [H16
2c5c0 33 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48  353] [H16354] [H
2c5d0 31 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a  16355] [H16358].
2c5e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2c5f0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2c600 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c610 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
2c620 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
2c630 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
2c640 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33  e {H12850} <S603
2c650 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
2c660 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2c670 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2c680 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2c690 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2c6a0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2c6b0 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2c6c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c6d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2c6e0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2c6f0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2c700 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2c710 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
2c720 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
2c730 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
2c740 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
2c750 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
2c760 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73   function. The s
2c770 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c780 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2c790 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2c7a0 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2c7b0 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e  n", "temp" or an
2c7c0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2c7d0 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
2c7e0 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
2c7f0 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49  table or NULL. I
2c800 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2c810 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2c820 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2c830 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2c840 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2c850 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2c860 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2c870 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2c880 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2c890 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2c8a0 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
2c8b0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2c8c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2c8d0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2c8e0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2c8f0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
2c900 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
2c910 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
2c920 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
2c930 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
2c940 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
2c950 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61  ..**.** Metadata
2c960 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
2c970 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
2c980 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
2c990 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
2c9a0 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
2c9b0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
2c9c0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
2c9d0 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72   Any of these ar
2c9e0 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a  guments may be.*
2c9f0 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  * NULL, in which
2ca00 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
2ca10 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
2ca20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f  of metadata is o
2ca30 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  mitted..**.** <b
2ca40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2ca50 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2ca60 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
2ca70 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
2ca80 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
2ca90 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
2caa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
2cab0 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
2cac0 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
2cad0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
2cae0 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
2caf0 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
2cb00 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
2cb10 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
2cb20 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
2cb30 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2cb40 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
2cb50 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
2cb60 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
2cb70 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
2cb80 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2cb90 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2cba0 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
2cbb0 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
2cbc0 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
2cbd0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2cbe0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2cbf0 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
2cc00 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2cc10 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2cc20 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
2cc30 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2cc40 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
2cc50 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
2cc60 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  the.** declarati
2cc70 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
2cc80 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2cc90 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
2cca0 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63  il the next.** c
2ccb0 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74  all to any SQLit
2ccc0 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
2ccd0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
2cce0 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
2ccf0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
2cd00 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2cd10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2cd20 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
2cd30 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
2cd40 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
2cd50 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
2cd60 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
2cd70 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
2cd80 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
2cd90 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
2cda0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
2cdb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
2cdc0 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
2cdd0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
2cde0 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
2cdf0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2ce00 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2ce10 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2ce20 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2ce30 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2ce40 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2ce50 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2ce60 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2ce70 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2ce80 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2ce90 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2cea0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2ceb0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2cec0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2ced0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2cee0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2cef0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
2cf00 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
2cf10 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
2cf20 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
2cf30 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
2cf40 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
2cf50 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
2cf60 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
2cf70 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
2cf80 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
2cf90 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
2cfa0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2cfb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
2cfc0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2cfd0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
2cfe0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cff0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
2d000 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
2d010 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
2d020 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2d030 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
2d040 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2d050 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2d060 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2d070 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2d080 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2d090 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
2d0a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
2d0b0 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
2d0c0 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
2d0d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2d0f0 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
2d100 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2d110 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
2d120 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
2d130 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
2d140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
2d150 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
2d160 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
2d170 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
2d180 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
2d190 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
2d1a0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
2d1b0 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
2d1c0 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
2d1d0 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
2d1e0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
2d1f0 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
2d200 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
2d210 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
2d220 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
2d230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2d240 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2d250 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
2d260 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
2d270 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
2d280 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
2d290 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2d2a0 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
2d2b0 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
2d2c0 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
2d2d0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2d2e0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2d2f0 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
2d300 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2d310 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
2d320 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30  xtension {H12600
2d330 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20500>.**.**
2d340 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2d350 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
2d360 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2d370 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
2d380 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   file..**.** {H1
2d390 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65  2601} The sqlite
2d3a0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2d3b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2d3c0 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
2d3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2d3e0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2d3f0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
2d400 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
2d410 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32  e..**.** {H12602
2d420 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  } The entry poin
2d430 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a  t is zProc..**.*
2d440 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63  * {H12603} zProc
2d450 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2d460 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2d470 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2d480 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  oint.**         
2d490 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
2d4a0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
2d4b0 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  init"..**.** {H1
2d4c0 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65  2604} The sqlite
2d4d0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2d4e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  () interface sha
2d4f0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  ll return.**    
2d500 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
2d510 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
2d520 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2d530 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
2d540 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  s wrong..**.** {
2d550 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72  H12605} If an er
2d560 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
2d570 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
2d580 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
2d590 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d5a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2d5b0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2d5c0 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  l attempt to.** 
2d5d0 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70           fill *p
2d5e0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72  zErrMsg with err
2d5f0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2d600 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79  stored in memory
2d610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
2d620 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d630 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b  te3_malloc()]. {
2d640 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e  END}  The callin
2d650 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  g function.**   
2d660 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72         should fr
2d670 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
2d680 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2d690 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2d6a0 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e  * {H12606} Exten
2d6b0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2d6c0 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2d6d0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2d6e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
2d6f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2d700 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
2d710 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20  g this API,.**  
2d720 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73          otherwis
2d730 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
2d740 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
2d750 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
2d760 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
2d770 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2d780 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
2d790 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
2d7a0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
2d7b0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
2d7c0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2d7d0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2d7e0 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
2d7f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
2d800 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
2d810 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
2d820 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
2d830 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
2d840 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
2d850 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
2d860 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
2d870 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
2d880 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
2d890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2d8a0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2d8b0 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2d8c0 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30  ng {H12620} <S20
2d8d0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  500>.**.** So as
2d8e0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
2d8f0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
2d900 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
2d910 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
2d920 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
2d930 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
2d940 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
2d950 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
2d960 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
2d970 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
2d980 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
2d990 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
2d9a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
2d9b0 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  * is provided to
2d9c0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
2d9d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2d9e0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
2d9f0 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a  n and off..**.**
2da00 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   Extension loadi
2da10 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
2da20 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
2da30 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48   #1863..**.** {H
2da40 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20  12621} Call the 
2da50 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
2da60 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2da70 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
2da80 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20  ff==1.**        
2da90 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73    to turn extens
2daa0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
2dab0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
2dac0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
2dad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20  .**          it 
2dae0 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
2daf0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45  **.** {H12622} E
2db00 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2db10 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
2db20 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  lt..*/.int sqlit
2db30 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2db40 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
2db50 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
2db60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2db70 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  F: Automatically
2db80 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2db90 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32  ons {H12640} <S2
2dba0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2dbb0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
2dbc0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
2dbd0 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
2dbe0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
2dbf0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
2dc00 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
2dc10 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
2dc20 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
2dc30 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
2dc40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dc50 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ns]. {END}.**.**
2dc60 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
2dc70 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
2dc80 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
2dc90 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
2dca0 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20   is.** obtained 
2dcb0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2dcc0 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75  lloc()].  If you
2dcd0 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
2dce0 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e  ak checker.** on
2dcf0 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
2dd00 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
2dd10 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
2dd20 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b  his array, invok
2dd30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  e.** [sqlite3_re
2dd40 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2dd50 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73  on()] prior to s
2dd60 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20  hutdown to free 
2dd70 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  the memory..**.*
2dd80 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20  * {H12641} This 
2dd90 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
2dda0 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
2ddb0 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
2ddc0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ddd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2dde0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2ddf0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
2de00 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20  onnection].**   
2de10 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64         is opened
2de20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2de30 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2de40 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
2de50 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2de60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
2de70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20  .**.** {H12642} 
2de80 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
2de90 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
2dea0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
2deb0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20  s routine.**    
2dec0 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74        multiple t
2ded0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2dee0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
2def0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
2df00 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f  {H12643} This ro
2df10 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
2df20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
2df30 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
2df40 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ray.**          
2df50 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64  that is obtained
2df60 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2df70 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alloc()]..**.** 
2df80 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74  {H12644} Automat
2df90 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70  ic extensions ap
2dfa0 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74  ply across all t
2dfb0 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  hreads..*/.int s
2dfc0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2dfd0 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e  nsion(void (*xEn
2dfe0 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29  tryPoint)(void))
2dff0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e000 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
2e010 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
2e020 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53  ding {H12660} <S
2e030 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2e040 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
2e050 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73  les all previous
2e060 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75  ly registered au
2e070 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e  tomatic.** exten
2e080 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74  sions. {END}  It
2e090 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
2e0a0 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
2e0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
2e0c0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
2e0d0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  lls..**.** {H126
2e0e0 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  61} This functio
2e0f0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
2e100 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
2e110 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
2e120 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
2e130 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  sions..**.** {H1
2e140 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74  2662} This funct
2e150 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74  ion disables aut
2e160 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2e170 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73  s in all threads
2e180 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2e190 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
2e1a0 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f  ension(void);../
2e1b0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
2e1c0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
2e1d0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
2e1e0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
2e1f0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
2e200 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
2e210 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
2e220 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
2e230 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
2e240 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
2e250 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
2e260 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
2e270 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
2e280 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
2e290 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
2e2a0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
2e2b0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
2e2c0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
2e2d0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
2e2e0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
2e2f0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
2e300 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
2e310 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
2e320 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
2e330 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
2e340 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
2e350 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
2e360 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63  .*/../*.** Struc
2e370 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68  tures used by th
2e380 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
2e390 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70  interface.*/.typ
2e3a0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2e3b0 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33  te3_vtab sqlite3
2e3c0 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73  _vtab;.typedef s
2e3d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2e3e0 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
2e3f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70  _index_info;.typ
2e400 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2e410 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
2e420 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2e430 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72  sor;.typedef str
2e440 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
2e450 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  le sqlite3_modul
2e460 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2e470 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2e480 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30  e Object {H18000
2e490 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2e4a0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2e4b0 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
2e4c0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
2e4d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2e4e0 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
2e4f0 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
2e500 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61  lled a a "virtua
2e510 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
2e520 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
2e530 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e540 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
2e550 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
2e560 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
2e570 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
2e580 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
2e590 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69  dule..**.** A vi
2e5a0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2e5b0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
2e5c0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
2e5d0 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
2e5e0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
2e5f0 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
2e600 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
2e610 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
2e620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2e630 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
2e640 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e650 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
2e660 2a 20 54 68 65 20 72 65 67 69 73 74 72 61 74 69  * The registrati
2e670 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
2e680 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
2e690 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
2e6a0 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
2e6b0 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
2e6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e6d0 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
2e6e0 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
2e6f0 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
2e700 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
2e710 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
2e720 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
2e730 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e740 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
2e750 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
2e760 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
2e770 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
2e780 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
2e790 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
2e7a0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
2e7b0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
2e7c0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
2e7d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
2e7e0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
2e7f0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
2e800 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
2e810 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
2e820 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2e830 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
2e840 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
2e850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
2e860 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
2e870 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
2e880 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
2e890 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2e8a0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
2e8b0 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
2e8c0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
2e8d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2e8e0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2e8f0 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
2e900 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2e910 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
2e920 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2e930 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
2e940 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
2e950 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
2e960 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
2e970 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
2e980 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
2e990 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2e9a0 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
2e9b0 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
2e9c0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
2e9d0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
2e9e0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
2e9f0 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
2ea00 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
2ea10 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2ea20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
2ea30 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
2ea40 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
2ea50 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2ea60 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
2ea70 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
2ea80 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
2ea90 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2eaa0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
2eab0 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
2eac0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
2ead0 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
2eae0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
2eaf0 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
2eb00 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
2eb10 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
2eb20 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2eb30 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
2eb40 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2eb50 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
2eb60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2eb70 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2eb80 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
2eb90 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2eba0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
2ebb0 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
2ebc0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
2ebd0 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
2ebe0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
2ebf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ec00 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
2ec10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ec20 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2ec30 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
2ec40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2ec50 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
2ec60 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
2ec70 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2ec80 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
2ec90 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
2eca0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
2ecb0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
2ecc0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48  g Information {H
2ecd0 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18100} <S20400>.
2ece0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2ecf0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
2ed00 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2ed10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ed20 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
2ed30 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
2ed40 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
2ed50 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
2ed60 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
2ed70 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
2ed80 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
2ed90 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20  [xBestIndex].** 
2eda0 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72  method of a [vir
2edb0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2edc0 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  e].  The fields 
2edd0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
2ede0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
2edf0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
2ee00 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
2ee10 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
2ee20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
2ee30 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
2ee40 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
2ee50 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
2ee60 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
2ee70 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
2ee80 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2ee90 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
2eea0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d  **.** <pre>colum
2eeb0 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a  n OP expr</pre>.
2eec0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
2eed0 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
2eee0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
2eef0 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  .  The particula
2ef00 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
2ef10 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
2ef20 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
2ef30 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2ef40 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
2ef50 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
2ef60 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
2ef70 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
2ef80 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
2ef90 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
2efa0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2efb0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
2efc0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
2efd0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
2efe0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
2eff0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
2f000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
2f010 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
2f020 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
2f030 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
2f040 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
2f050 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
2f060 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
2f070 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
2f080 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
2f090 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
2f0a0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
2f0b0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
2f0c0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
2f0d0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
2f0e0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
2f0f0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
2f100 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
2f110 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
2f120 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
2f130 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
2f140 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
2f150 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
2f160 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
2f170 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
2f180 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
2f190 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
2f1a0 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
2f1b0 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
2f1c0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
2f1d0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
2f1e0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2f1f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65  ..**.** The [xBe
2f200 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20  stIndex] method 
2f210 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
2f220 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
2f230 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2f240 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
2f250 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
2f260 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
2f270 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
2f280 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
2f290 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
2f2a0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
2f2b0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
2f2c0 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
2f2d0 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
2f2e0 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
2f2f0 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
2f300 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
2f310 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
2f320 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
2f330 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
2f340 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
2f350 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
2f360 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
2f370 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
2f380 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
2f390 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
2f3a0 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
2f3b0 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
2f3c0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
2f3d0 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65  .** [xFilter] me
2f3e0 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  thod..** [sqlite
2f3f0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
2f400 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
2f410 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66   if and only iff
2f420 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64  .** needToFreeId
2f430 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
2f440 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43  .** The orderByC
2f450 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
2f460 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
2f470 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
2f480 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
2f490 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
2f4a0 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
2f4b0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2f4c0 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
2f4d0 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
2f4e0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
2f4f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73  ed..**.** The es
2f500 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
2f510 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
2f520 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
2f530 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
2f540 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
2f550 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
2f560 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
2f570 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
2f580 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
2f590 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
2f5a0 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
2f5b0 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
2f5c0 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
2f5d0 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
2f5e0 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
2f5f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2f600 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
2f610 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
2f620 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
2f630 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
2f640 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
2f650 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
2f660 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2f670 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
2f680 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
2f690 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
2f6a0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
2f6b0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
2f6c0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
2f6d0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
2f6e0 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
2f6f0 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
2f700 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
2f710 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
2f720 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
2f730 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
2f740 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
2f750 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
2f760 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
2f770 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
2f780 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
2f790 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
2f7a0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
2f7b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
2f7c0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
2f7d0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
2f7e0 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
2f7f0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
2f800 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
2f810 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
2f820 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
2f830 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
2f840 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
2f850 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
2f860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2f870 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
2f880 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
2f890 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
2f8a0 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
2f8b0 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
2f8c0 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
2f8d0 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
2f8e0 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
2f8f0 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
2f900 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
2f910 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2f920 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
2f930 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
2f940 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
2f950 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
2f960 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
2f970 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
2f980 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
2f990 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
2f9a0 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
2f9b0 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
2f9c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
2f9d0 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
2f9e0 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
2f9f0 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
2fa00 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
2fa10 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
2fa20 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
2fa30 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
2fa40 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
2fa50 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
2fa60 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
2fa70 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
2fa80 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
2fa90 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
2faa0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
2fab0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
2fac0 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
2fad0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
2fae0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
2faf0 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
2fb00 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
2fb10 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
2fb20 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
2fb30 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
2fb40 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
2fb50 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
2fb60 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2fb70 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
2fb80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
2fb90 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
2fba0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2fbb0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
2fbc0 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
2fbd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
2fbe0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
2fbf0 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
2fc00 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
2fc10 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
2fc20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2fc30 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
2fc40 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
2fc50 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
2fc60 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
2fc70 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
2fc80 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34  n {H18200} <S204
2fc90 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
2fca0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  TAL.**.** This r
2fcb0 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
2fcc0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
2fcd0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
2fce0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
2fcf0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
2fd00 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
2fd10 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74   before.** creat
2fd20 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ing a new [virtu
2fd30 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20  al table] using 
2fd40 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62  the module, or b
2fd50 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a  efore using a.**
2fd60 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69   preexisting [vi
2fd70 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72  rtual table] for
2fd80 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
2fd90 2a 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  ** The module na
2fda0 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
2fdb0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
2fdc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
2fdd0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
2fde0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2fdf0 72 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  r.  The name of 
2fe00 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
2fe10 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
2fe20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
2fe30 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
2fe40 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
2fe50 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70  er to.** the imp
2fe60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2fe70 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
2fe80 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65  e module].   The
2fe90 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d   fourth.** param
2fea0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
2feb0 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61  rary client data
2fec0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
2fed0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
2fee0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72  ** into the [xCr
2fef0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
2ff00 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
2ff10 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2ff20 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e  e module.** when
2ff30 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74   a new virtual t
2ff40 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67  able is be being
2ff50 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e   created or rein
2ff60 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  itialized..**.**
2ff70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2ff80 68 61 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  has exactly the 
2ff90 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 63  same effect as c
2ffa0 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  alling.** [sqlit
2ffb0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2ffc0 5f 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55  _v2()] with a NU
2ffd0 4c 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64  LL client data d
2ffe0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51  estructor..*/.SQ
2fff0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
30000 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
30010 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
30020 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
30030 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
30040 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
30050 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
30060 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
30070 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
30080 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
30090 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
300a0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
300b0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
300c0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
300d0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
300e0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
300f0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
30100 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
30110 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
30120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30130 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
30140 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
30150 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31  mentation {H1821
30160 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45  0} <S20400>.** E
30170 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
30180 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
30190 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74  s identical to t
301a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
301b0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74  te_module()] met
301c0 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74  hod,.** except t
301d0 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 78  hat it has an ex
301e0 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tra parameter to
301f0 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64   specify .** a d
30200 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
30210 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e  on for the clien
30220 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  t data pointer. 
30230 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
30240 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
30250 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
30260 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
30270 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
30280 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
30290 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
302a0 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a  a pointer.  .*/.
302b0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
302c0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
302d0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
302e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
302f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30300 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
30310 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
30320 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
30330 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
30340 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
30350 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
30360 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
30370 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
30380 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
30390 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
303a0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
303b0 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
303c0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
303d0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
303e0 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
303f0 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
30400 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
30410 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
30420 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
30430 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
30440 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
30450 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30  ct {H18010} <S20
30460 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
30470 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
30480 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
30490 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
304a0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
304b0 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
304c0 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
304d0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  .** of the follo
304e0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74  wing structure t
304f0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
30500 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
30510 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
30520 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63  ual table].  Eac
30530 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
30540 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
30550 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
30560 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
30570 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
30580 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73  n..** The purpos
30590 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
305a0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
305b0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
305c0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d   that are.** com
305d0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  mon to all modul
305e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
305f0 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  s..**.** Virtual
30600 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
30610 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
30620 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
30630 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
30640 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
30650 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
30660 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
30670 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
30680 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
30690 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
306a0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
306b0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
306c0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
306d0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
306e0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
306f0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74  to zErrMsg.  Aft
30700 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
30710 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
30720 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63  ered up to the c
30730 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  lient applicatio
30740 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  n, the string wi
30750 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
30760 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20  lly.** freed by 
30770 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
30780 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  nd the zErrMsg f
30790 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72  ield will be zer
307a0 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  oed..*/.struct s
307b0 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
307c0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
307d0 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
307e0 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
307f0 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
30800 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
30810 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
30820 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20            /* NO 
30830 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20  LONGER USED */. 
30840 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
30850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30860 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
30870 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
30880 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
30890 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
308a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
308b0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
308c0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
308d0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
308e0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
308f0 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
30900 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d  Object  {H18020}
30910 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
30920 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
30930 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
30940 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
30950 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
30960 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  L.**.** Every [v
30970 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30980 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
30990 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
309a0 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
309b0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
309c0 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
309d0 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
309e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
309f0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
30a00 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
30a10 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
30a20 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
30a30 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
30a40 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
30a50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
30a60 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
30a70 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
30a80 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
30a90 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
30aa0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
30ab0 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
30ac0 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73  e] method.  Cuss
30ad0 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
30ae0 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
30af0 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
30b00 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
30b10 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
30b20 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
30b30 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
30b40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30b50 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
30b60 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
30b70 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
30b80 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
30b90 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
30ba0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
30bb0 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
30bc0 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
30bd0 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
30be0 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
30bf0 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
30c00 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
30c10 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
30c20 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
30c30 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
30c40 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
30c50 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
30c60 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
30c70 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
30c80 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
30c90 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
30ca0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
30cb0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
30cc0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
30cd0 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
30ce0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31  irtual Table {H1
30cf0 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8280} <S20400>.*
30d00 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
30d10 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74  *.** The [xCreat
30d20 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
30d30 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
30d40 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
30d50 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
30d60 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
30d70 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
30d80 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
30d90 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
30da0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
30db0 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
30dc0 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
30dd0 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  lement..*/.SQLIT
30de0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
30df0 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
30e00 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
30e10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
30e20 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
30e30 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
30e40 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
30e50 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48  Virtual Table {H
30e60 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18300} <S20400>.
30e70 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
30e80 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
30e90 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
30ea0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
30eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30ec0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
30ed0 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
30ee0 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
30ef0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
30f00 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
30f10 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
30f20 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
30f30 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
30f40 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
30f50 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
30f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
30f70 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
30f80 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
30f90 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
30fa0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
30fb0 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
30fc0 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
30fd0 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
30fe0 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
30ff0 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
31000 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
31010 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
31020 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
31030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
31040 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
31050 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
31060 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
31070 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
31080 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
31090 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
310a0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
310b0 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
310c0 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
310d0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
310e0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
310f0 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
31100 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
31110 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
31120 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
31130 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
31140 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
31150 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
31160 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31170 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
31180 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
31190 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
311a0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
311b0 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
311c0 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
311d0 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
311e0 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
311f0 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
31200 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
31210 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
31220 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
31230 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
31240 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
31250 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
31260 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
31270 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
31280 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
31290 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
312a0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
312b0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
312c0 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
312d0 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
312e0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
312f0 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
31300 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
31310 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
31320 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
31330 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
31340 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
31350 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
31360 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
31370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
31380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
31390 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
313a0 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d  en BLOB {H17800}
313b0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59   <S30230>.** KEY
313c0 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
313d0 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
313e0 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
313f0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
31400 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
31410 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
31420 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
31430 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
31440 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
31450 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
31460 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73  rmed..** Objects
31470 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
31480 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
31490 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
314a0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
314b0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
314c0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
314d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
314e0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
314f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
31500 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
31510 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
31520 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
31530 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
31540 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
31550 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
31560 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
31570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31580 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
31590 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a   BLOB in bytes..
315a0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
315b0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
315c0 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
315d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
315e0 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
315f0 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48  cremental I/O {H
31600 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17810} <S30230>.
31610 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
31620 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
31630 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
31640 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
31650 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
31660 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
31670 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
31680 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
31690 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
316a0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
316b0 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
316c0 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
316d0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
316e0 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
316f0 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
31700 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
31710 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
31720 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
31730 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
31740 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
31750 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c  ero, then the BL
31760 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
31770 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69   read.** and wri
31780 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
31790 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
317a0 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
317b0 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
317c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
317d0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
317e0 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
317f0 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
31800 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
31810 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
31820 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
31830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
31840 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e  hat.** is assign
31850 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
31860 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
31870 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
31880 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69  ..** For the mai
31890 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
318a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
318b0 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a  me is "main"..**
318c0 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   For TEMP tables
318d0 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
318e0 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a  ame is "temp"..*
318f0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
31900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
31910 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65  returned and the
31920 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   new [BLOB handl
31930 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  e] is written.**
31940 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68   to *ppBlob. Oth
31950 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
31960 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
31970 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69  ed and *ppBlob i
31980 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61  s set.** to be a
31990 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a   null pointer..*
319a0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
319b0 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
319c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
319d0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
319e0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
319f0 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
31a00 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
31a10 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
31a20 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
31a30 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f  * functions.  No
31a40 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
31a50 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
31a60 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
31a70 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
31a80 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
31a90 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
31aa0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
31ab0 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
31ac0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
31ad0 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
31ae0 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
31af0 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  utine..**.** If 
31b00 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42  the row that a B
31b10 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74  LOB handle point
31b20 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64  s to is modified
31b30 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54   by an.** [UPDAT
31b40 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72  E], [DELETE], or
31b50 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54   by [ON CONFLICT
31b60 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a  ] side-effects.*
31b70 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  * then the BLOB 
31b80 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64  handle is marked
31b90 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a   as "expired"..*
31ba0 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69  * This is true i
31bb0 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20  f any column of 
31bc0 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67  the row is chang
31bd0 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d  ed, even a colum
31be0 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  n.** other than 
31bf0 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42  the one the BLOB
31c00 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20   handle is open 
31c10 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20  on..** Calls to 
31c20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
31c30 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
31c40 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
31c50 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65   for.** a expire
31c60 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61  d BLOB handle fa
31c70 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72  il with an retur
31c80 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  n code of [SQLIT
31c90 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61  E_ABORT]..** Cha
31ca0 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74  nges written int
31cb0 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74  o a BLOB prior t
31cc0 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72  o the BLOB expir
31cd0 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  ing are not.** r
31ce0 6f 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65  ollback by the e
31cf0 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
31d00 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61   BLOB.  Such cha
31d10 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  nges will eventu
31d20 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69  ally.** commit i
31d30 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
31d40 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  n continues to c
31d50 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
31d60 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
31d70 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
31d80 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74  interface to det
31d90 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20  ermine the size 
31da0 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64  of.** the opened
31db0 20 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65   blob.  The size
31dc0 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e   of a blob may n
31dd0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ot be changed by
31de0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
31df0 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50  ce.  Use the [UP
31e00 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  DATE] SQL comman
31e10 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
31e20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f  size of a.** blo
31e30 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  b..**.** The [sq
31e40 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
31e50 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lob()] and [sqli
31e60 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
31e70 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65  lob()] interface
31e80 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69  s.** and the bui
31e90 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d  lt-in [zeroblob]
31ea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61   SQL function ca
31eb0 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65  n be used, if de
31ec0 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65  sired,.** to cre
31ed0 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65  ate an empty, ze
31ee0 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69  ro-filled blob i
31ef0 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20  n which to read 
31f00 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a  or write using.*
31f10 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  * this interface
31f20 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ..**.** To avoid
31f30 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b   a resource leak
31f40 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c  , every open [BL
31f50 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c  OB handle] shoul
31f60 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  d eventually.** 
31f70 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61  be released by a
31f80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31f90 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
31fa0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
31fb0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d  nts:.** [H17813]
31fc0 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31   [H17814] [H1781
31fd0 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37  6] [H17819] [H17
31fe0 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f  821] [H17824].*/
31ff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
32000 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
32010 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
32020 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
32030 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
32040 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
32050 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
32060 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
32070 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
32080 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
32090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
320a0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
320b0 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20  Handle {H17830} 
320c0 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S30230>.**.** C
320d0 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
320e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
320f0 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  ** Closing a BLO
32100 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
32110 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
32120 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
32130 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
32140 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
32150 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
32160 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
32170 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
32180 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
32190 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
321a0 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e   mode]..** If an
321b0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
321c0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
321d0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
321e0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
321f0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
32200 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
32210 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
32220 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f   Closing the BLO
32230 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74  B often forces t
32240 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75  he changes.** ou
32250 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f  t to disk and so
32260 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f   if any I/O erro
32270 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77  rs occur, they w
32280 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72  ill likely occur
32290 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20  .** at the time 
322a0 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  when the BLOB is
322b0 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72   closed.  Any er
322c0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
322d0 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e  during.** closin
322e0 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61  g are reported a
322f0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  s a non-zero ret
32300 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  urn value..**.**
32310 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   The BLOB is clo
32320 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
32330 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
32340 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
32350 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
32360 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB is
32370 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a   still closed..*
32380 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
32390 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
323a0 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77   null pointer (w
323b0 68 69 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65  hich as would be
323c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
323d0 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b  failed call to [
323e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
323f0 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c  n()]) is a harml
32400 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
32410 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
32420 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38  * [H17833] [H178
32430 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a  36] [H17839].*/.
32440 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
32450 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62  _close(sqlite3_b
32460 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
32470 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
32480 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f  The Size Of An O
32490 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30  pen BLOB {H17840
324a0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
324b0 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   Returns the siz
324c0 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
324d0 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c  e BLOB accessibl
324e0 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75  e via the .** su
324f0 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65  ccessfully opene
32500 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
32510 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  in its only argu
32520 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  ment.  The.** in
32530 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49  cremental blob I
32540 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  /O routines can 
32550 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65  only read or ove
32560 72 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e  rwriting existin
32570 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e  g.** blob conten
32580 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63  t; they cannot c
32590 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
325a0 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  f a blob..**.** 
325b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
325c0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
325d0 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
325e0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
325f0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
32600 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
32610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
32620 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
32630 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
32640 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
32650 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
32660 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
32670 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
32680 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
32690 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
326a0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
326b0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
326c0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
326d0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
326e0 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f  :.** [H17843].*/
326f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
32700 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  b_bytes(sqlite3_
32710 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
32720 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44  CAPI3REF: Read D
32730 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20  ata From A BLOB 
32740 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48  Incrementally {H
32750 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17850} <S30230>.
32760 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
32770 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
32780 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
32790 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
327a0 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61  le] into a.** ca
327b0 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
327c0 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66  ffer. N bytes of
327d0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
327e0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a   into buffer Z.*
327f0 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20  * from the open 
32800 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61  BLOB, starting a
32810 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
32820 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65  ..**.** If offse
32830 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
32840 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
32850 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
32860 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
32870 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
32880 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
32890 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20  ta is read.  If 
328a0 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a  N or iOffset is.
328b0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
328c0 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  o, [SQLITE_ERROR
328d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
328e0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
328f0 64 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f  d..** The size o
32900 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20  f the blob (and 
32910 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75  hence the maximu
32920 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66  m value of N+iOf
32930 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20  fset).** can be 
32940 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
32950 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
32960 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
32970 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  rface..**.** An 
32980 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
32990 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20  from an expired 
329a0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
329b0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
329c0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
329d0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
329e0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
329f0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
32a00 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
32a10 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
32a20 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
32a30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
32a40 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
32a50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
32a60 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
32a70 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
32a80 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
32a90 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
32aa0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
32ab0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
32ac0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
32ad0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
32ae0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
32af0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
32b00 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
32b10 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
32b20 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
32b30 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
32b40 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
32b50 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
32b60 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
32b70 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
32b80 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
32b90 72 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  rite()]..**.** R
32ba0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
32bb0 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36  [H17853] [H17856
32bc0 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38  ] [H17859] [H178
32bd0 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31  62] [H17863] [H1
32be0 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a  7865] [H17868].*
32bf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
32c00 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f  ob_read(sqlite3_
32c10 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c  blob *, void *Z,
32c20 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66   int N, int iOff
32c30 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
32c40 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74  I3REF: Write Dat
32c50 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
32c60 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37  crementally {H17
32c70 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  870} <S30230>.**
32c80 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
32c90 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
32ca0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
32cb0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
32cc0 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
32cd0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
32ce0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
32cf0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
32d00 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20  from the buffer 
32d10 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70  Z.** into the op
32d20 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
32d30 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
32d40 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  set..**.** If th
32d50 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
32d60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
32d70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73  rst argument was
32d80 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a   not opened for.
32d90 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  ** writing (the 
32da0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
32db0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
32dc0 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72  _open()] was zer
32dd0 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  o),.** this func
32de0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
32df0 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
32e00 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
32e10 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
32e20 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
32e30 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
32e40 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
32e50 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
32e60 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
32e70 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
32e80 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20  I..** If offset 
32e90 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
32ea0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
32eb0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
32ec0 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
32ed0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
32ee0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
32ef0 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66   is written.  If
32f00 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
32f10 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
32f20 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
32f30 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
32f40 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
32f50 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
32f60 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
32f70 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
32f80 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
32f90 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
32fa0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
32fb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
32fc0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
32fd0 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20  *.** An attempt 
32fe0 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
32ff0 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
33000 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
33010 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
33020 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
33030 54 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  T].  Writes to t
33040 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63  he BLOB that occ
33050 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20  urred.** before 
33060 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
33070 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f  ] expired are no
33080 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  t rolled back by
33090 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69   the.** expirati
330a0 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65  on of the handle
330b0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
330c0 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  se those changes
330d0 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62   might.** have b
330e0 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20  een overwritten 
330f0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
33100 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68   that expired th
33110 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a  e BLOB handle.**
33120 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64   or by other ind
33130 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65  ependent stateme
33140 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  nts..**.** On su
33150 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
33160 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
33170 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20   Otherwise, an  
33180 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
33190 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
331a0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
331b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
331c0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
331d0 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
331e0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
331f0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
33200 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
33210 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
33220 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33230 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
33240 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
33250 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
33260 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
33270 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
33280 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
33290 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
332a0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
332b0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
332c0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
332d0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
332e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
332f0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e  e3_blob_read()].
33300 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
33310 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d  nts:.** [H17873]
33320 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37   [H17874] [H1787
33330 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37  5] [H17876] [H17
33340 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48  877] [H17879] [H
33350 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a  17882] [H17885].
33360 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69  ** [H17888].*/.i
33370 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33380 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
33390 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
333a0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
333b0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
333c0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
333d0 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
333e0 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20  bjects {H11200} 
333f0 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
33400 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
33410 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
33420 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
33430 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
33440 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
33450 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
33460 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
33470 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
33480 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
33490 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
334a0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
334b0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
334c0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
334d0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
334e0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
334f0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
33500 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
33510 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
33520 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
33530 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
33540 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
33550 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33560 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
33570 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
33580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
33590 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
335a0 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63  ..** Names are c
335b0 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a  ase sensitive..*
335c0 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f  * Names are zero
335d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
335e0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  8 strings..** If
335f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
33600 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
33610 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
33620 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  ** If zVfsName i
33630 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
33640 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
33650 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  eturned..**.** N
33660 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
33670 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
33680 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
33690 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77  r()..** Each new
336a0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
336b0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
336c0 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
336d0 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65  g is set..** The
336e0 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
336f0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
33700 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
33710 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f  ut injury..** To
33720 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
33730 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
33740 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
33750 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
33760 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
33770 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
33780 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
33790 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
337a0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
337b0 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
337c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
337d0 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
337e0 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
337f0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
33800 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
33810 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
33820 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
33830 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
33840 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  .**.** Unregiste
33850 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
33860 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
33870 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
33880 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
33890 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
338a0 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
338b0 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
338c0 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
338d0 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
338e0 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
338f0 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
33900 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
33910 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b  s:.** [H11203] [
33920 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d  H11206] [H11209]
33930 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31   [H11212] [H1121
33940 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73  5] [H11218].*/.s
33950 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
33960 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
33970 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
33980 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
33990 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
339a0 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
339b0 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
339c0 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
339d0 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
339e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
339f0 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31  REF: Mutexes {H1
33a00 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7000} <S20000>.*
33a10 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
33a20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
33a30 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
33a40 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
33a50 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
33a60 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
33a70 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
33a80 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
33a90 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
33aa0 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
33ab0 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
33ac0 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
33ad0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
33ae0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
33af0 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
33b00 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
33b10 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
33b20 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
33b30 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
33b40 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
33b50 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
33b60 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
33b70 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
33b80 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  ime.  The follow
33b90 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
33ba0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
33bb0 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
33bc0 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
33bd0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
33be0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
33bf0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
33c00 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
33c10 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
33c20 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
33c30 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
33c40 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NOOP.** </ul>.**
33c50 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
33c60 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
33c70 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
33c80 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
33c90 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
33ca0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
33cb0 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
33cc0 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
33cd0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
33ce0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
33cf0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
33d00 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
33d10 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
33d20 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
33d30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
33d40 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
33d50 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
33d60 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
33d70 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ndows..**.** If 
33d80 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
33d90 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
33da0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
33db0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
33dc0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
33dd0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
33de0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
33df0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
33e00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33e10 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
33e20 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
33e30 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
33e40 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
33e50 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
33e60 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
33e70 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
33e80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
33e90 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
33ea0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
33eb0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
33ec0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
33ed0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
33ee0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
33ef0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
33f00 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
33f10 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
33f20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
33f30 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ()..**.** {H1701
33f40 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
33f50 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
33f60 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
33f70 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
33f80 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
33f90 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30  ter to it. {H170
33fa0 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e  12} If it return
33fb0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
33fc0 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
33fd0 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
33fe0 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31  llocated. {H1701
33ff0 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  3} SQLite.** wil
34000 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61  l unwind its sta
34010 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ck and return an
34020 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d   error. {H17014}
34030 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   The argument.**
34040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
34050 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
34060 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
34070 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
34080 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
34090 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
340a0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
340b0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
340c0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
340d0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
340e0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
340f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
34100 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
34110 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34120 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
34130 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
34140 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
34150 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
34160 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
34170 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
34180 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
34190 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48  * </ul>.**.** {H
341a0 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74  17015} The first
341b0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
341c0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
341d0 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
341e0 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
341f0 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
34200 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
34210 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
34220 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
34230 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
34240 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
34250 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
34260 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b  _FAST is used. {
34270 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65  END}.** The mute
34280 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
34290 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
342a0 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
342b0 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
342c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
342d0 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
342e0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
342f0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
34300 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36  ant to.  {H17016
34310 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c  } But SQLite wil
34320 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
34330 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
34340 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
34350 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
34360 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49  ds one.  {END} I
34370 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72  f a faster non-r
34380 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a  ecursive mutex.*
34390 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
343a0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e   is available on
343b0 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f   the host platfo
343c0 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75  rm, the mutex su
343d0 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74  bsystem.** might
343e0 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d   return such a m
343f0 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65  utex in response
34400 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   to SQLITE_MUTEX
34410 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  _FAST..**.** {H1
34420 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20  7017} The other 
34430 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
34440 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
34450 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68  tex_alloc() each
34460 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
34470 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
34480 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
34490 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20  ex. {END}  Four 
344a0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
344b0 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
344c0 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
344d0 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
344e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
344f0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
34500 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
34510 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
34520 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
34530 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
34540 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
34550 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
34560 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
34570 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
34580 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
34590 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
345a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
345b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
345c0 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
345d0 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
345e0 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f  *.** {H17018} No
345f0 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f  te that if one o
34600 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  f the dynamic mu
34610 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28  tex parameters (
34620 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
34630 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d  T.** or SQLITE_M
34640 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
34650 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c  is used then sql
34660 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
34670 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
34680 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20  different mutex 
34690 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20  on every call.  
346a0 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72  {H17034} But for
346b0 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d   the static.** m
346c0 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20  utex types, the 
346d0 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65  same mutex is re
346e0 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20  turned on every 
346f0 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a  call that has.**
34700 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e   the same type n
34710 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  umber..**.** {H1
34720 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65  7019} The sqlite
34730 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72  3_mutex_free() r
34740 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74  outine deallocat
34750 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a  es a previously.
34760 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e  ** allocated dyn
34770 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37  amic mutex. {H17
34780 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63  020} SQLite is c
34790 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
347a0 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
347b0 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
347c0 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b   it allocates. {
347d0 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61  A17021} The dyna
347e0 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
347f0 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73   not be in.** us
34800 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
34810 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31  deallocated. {A1
34820 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67  7022} Attempting
34830 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
34840 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
34850 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
34860 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
34870 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20  {H17023} SQLite 
34880 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
34890 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
348a0 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  tex. {END}.**.**
348b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
348c0 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
348d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
348e0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
348f0 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
34900 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34  a mutex. {H17024
34910 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
34920 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
34930 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
34940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
34950 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
34960 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
34970 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
34980 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
34990 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35  TE_BUSY. {H17025
349a0 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  }  The sqlite3_m
349b0 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
349c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
349d0 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e  LITE_OK].** upon
349e0 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
349f0 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74  y.  {H17026} Mut
34a00 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
34a10 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
34a20 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
34a30 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
34a40 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
34a50 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
34a60 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75  * {H17027} In su
34a70 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
34a80 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
34a90 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
34aa0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
34ab0 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
34ac0 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
34ad0 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20  r.  {A17028} If 
34ae0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34af0 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
34b00 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
34b10 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
34b20 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
34b30 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
34b40 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d  ned..** {H17029}
34b50 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
34b60 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75  er exhibit.** su
34b70 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69  ch behavior in i
34b80 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75  ts own use of mu
34b90 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  texes..**.** Som
34ba0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
34bb0 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
34bc0 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
34bd0 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
34be0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
34bf0 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
34c00 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
34c10 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
34c20 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
34c30 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
34c40 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
34c50 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20  .  {H17030} The 
34c60 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79  SQLite core only
34c70 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71   ever uses.** sq
34c80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
34c90 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61  ) as an optimiza
34ca0 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20  tion so this is 
34cb0 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76  acceptable behav
34cc0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  ior..**.** {H170
34cd0 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  31} The sqlite3_
34ce0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
34cf0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
34d00 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
34d10 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
34d20 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
34d30 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d  hread.  {A17032}
34d40 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   The behavior.**
34d50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
34d60 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
34d70 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
34d80 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
34d90 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
34da0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
34db0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31   allocated.  {H1
34dc0 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  7033} SQLite wil
34dd0 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
34de0 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ther. {END}.**.*
34df0 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e  * If the argumen
34e00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
34e10 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69  ex_enter(), sqli
34e20 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c  te3_mutex_try(),
34e30 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   or.** sqlite3_m
34e40 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20  utex_leave() is 
34e50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
34e60 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72  then all three r
34e70 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76  outines.** behav
34e80 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  e as no-ops..**.
34e90 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
34ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
34eb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
34ec0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
34ed0 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
34ee0 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
34ef0 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
34f00 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
34f10 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
34f20 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
34f30 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
34f40 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
34f50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
34f60 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
34f70 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
34f80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
34f90 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
34fa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34fb0 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64  EF: Mutex Method
34fc0 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30  s Object {H17120
34fd0 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58  } <S20130>.** EX
34fe0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
34ff0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
35000 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64  this structure d
35010 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c  efines the low-l
35020 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  evel routines.**
35030 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74   used to allocat
35040 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65  e and use mutexe
35050 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79  s..**.** Usually
35060 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  , the default mu
35070 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
35080 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
35090 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75  SQLite are.** su
350a0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65  fficient, howeve
350b0 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74  r the user has t
350c0 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62  he option of sub
350d0 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74  stituting a cust
350e0 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  om.** implementa
350f0 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c  tion for special
35100 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73  ized deployments
35110 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20   or systems for 
35120 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20  which SQLite.** 
35130 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
35140 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
35150 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74  ementation. In t
35160 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73  his case, the us
35170 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e  er.** creates an
35180 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69  d populates an i
35190 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
351a0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73  structure to pas
351b0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
351c0 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77  config() along w
351d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
351e0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
351f0 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  tion..** Additio
35200 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e  nally, an instan
35210 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
35220 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
35230 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74   as an.** output
35240 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71   variable when q
35250 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74  uerying the syst
35260 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  em for the curre
35270 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  nt mutex.** impl
35280 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e  ementation, usin
35290 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
352a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f  NFIG_GETMUTEX] o
352b0 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ption..**.** The
352c0 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
352d0 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
352e0 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
352f0 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
35300 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69  rt of system ini
35310 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74  tialization by t
35320 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
35330 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
35340 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68  ..** {H17001} Th
35350 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75  e xMutexInit rou
35360 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61  tine shall be ca
35370 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  lled by SQLite o
35380 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  nce for each.** 
35390 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
353a0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  o [sqlite3_initi
353b0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
353c0 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65  The xMutexEnd me
353d0 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20  thod defined by 
353e0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69  this structure i
353f0 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20  s invoked as.** 
35400 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73  part of system s
35410 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73  hutdown by the s
35420 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
35430 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a  ) function. The.
35440 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
35450 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64  n of this method
35460 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20   is expected to 
35470 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73  release all outs
35480 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75  tanding.** resou
35490 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79  rces obtained by
354a0 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f   the mutex metho
354b0 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ds implementatio
354c0 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a  n, especially.**
354d0 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20   those obtained 
354e0 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69  by the xMutexIni
354f0 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30  t method. {H1700
35500 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64  3} The xMutexEnd
35510 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
35520 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
35530 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
35540 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35550 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
35560 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
35570 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
35580 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
35590 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
355a0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
355b0 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
355c0 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
355d0 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
355e0 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
355f0 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
35600 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
35610 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
35620 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
35630 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
35640 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
35650 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
35660 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
35670 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
35680 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
35690 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
356a0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
356b0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
356c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
356d0 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
356e0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
356f0 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
35700 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
35710 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
35720 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
35730 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
35740 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
35750 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   </li>.** </ul>.
35760 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64  **.** The only d
35770 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61  ifference is tha
35780 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c  t the public sql
35790 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f  ite3_XXX functio
357a0 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a  ns enumerated.**
357b0 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20   above silently 
357c0 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63  ignore any invoc
357d0 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73  ations that pass
357e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
357f0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
35800 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
35810 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  le. The implemen
35820 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d  tations of the m
35830 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a  ethods defined.*
35840 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  * by this struct
35850 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75  ure are not requ
35860 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74  ired to handle t
35870 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65  his case, the re
35880 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73  sults.** of pass
35890 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
358a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
358b0 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64  valid mutex hand
358c0 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  le are undefined
358d0 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20  .** (i.e. it is 
358e0 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72  acceptable to pr
358f0 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65  ovide an impleme
35900 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67  ntation that seg
35910 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20  faults if.** it 
35920 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c  is passed a NULL
35930 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79   pointer)..*/.ty
35940 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
35950 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
35960 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
35970 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
35980 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
35990 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
359a0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
359b0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
359c0 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
359d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
359e0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
359f0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
35a00 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
35a10 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
35a20 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
35a30 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
35a40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
35a50 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
35a60 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
35a70 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
35a80 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
35a90 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
35aa0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
35ab0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
35ac0 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
35ad0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
35ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35af0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
35b00 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
35b10 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e  H17080} <S20130>
35b20 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
35b30 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
35b40 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
35b50 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
35b60 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
35b70 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
35b80 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
35b90 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
35ba0 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53  . {H17081} The S
35bb0 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
35bc0 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
35bd0 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
35be0 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
35bf0 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
35c00 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
35c10 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
35c20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
35c30 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20  .  {H17082} The 
35c40 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
35c50 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
35c60 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
35c70 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
35c80 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
35c90 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
35ca0 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31  DEBUG flag.  {A1
35cb0 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d  7087} External m
35cc0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
35cd0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79  ions.** are only
35ce0 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
35cf0 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69  vide these routi
35d00 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45  nes if SQLITE_DE
35d10 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65  BUG is.** define
35d20 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20  d and if NDEBUG 
35d30 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a  is not defined..
35d40 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54  **.** {H17083} T
35d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
35d60 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
35d70 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
35d80 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
35d90 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
35da0 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
35db0 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
35dc0 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
35dd0 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20  ** {X17084} The 
35de0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35df0 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
35e00 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
35e10 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
35e20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
35e30 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20  tually work. If 
35e40 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
35e50 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
35e60 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
35e70 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
35e80 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
35e90 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
35ea0 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74  ovide stubs that
35eb0 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72   always.** retur
35ec0 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
35ed0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
35ee0 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69  spurious asserti
35ef0 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
35f00 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74  ** {H17085} If t
35f10 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
35f20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
35f30 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
35f40 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
35f50 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
35f60 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44   return 1.  {END
35f70 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75  } This seems cou
35f80 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73  nter-intuitive s
35f90 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20  ince.** clearly 
35fa0 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74  the mutex cannot
35fb0 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64   be held if it d
35fc0 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20  oes not exist.  
35fd0 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72  But the.** the r
35fe0 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20  eason the mutex 
35ff0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
36000 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75  s because the bu
36010 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73  ild is not.** us
36020 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e  ing mutexes.  An
36030 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74  d we do not want
36040 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f   the assert() co
36050 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
36060 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36070 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20  mutex_held() to 
36080 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a  fail, so a non-z
36090 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a  ero return is.**
360a0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
360b0 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b   thing to do.  {
360c0 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69  H17086} The sqli
360d0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
360e0 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
360f0 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
36100 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
36110 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
36120 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36130 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
36140 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
36150 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
36160 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
36170 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
36180 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
36190 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31  pes {H17001} <H1
361a0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000>.**.** The 
361b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
361c0 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
361d0 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
361e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
361f0 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
36200 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
36210 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
36220 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
36230 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
36240 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
36250 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
36260 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
36270 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
36280 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
36290 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
362a0 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
362b0 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
362c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
362d0 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
362e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
362f0 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
36300 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
36310 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36320 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
36330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
36340 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
36350 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
36360 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
36370 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
36380 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
36390 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
363a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
363b0 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
363c0 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23  /* NOT USED */.#
363d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
363e0 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20  TEX_STATIC_OPEN 
363f0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
36400 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f  e3BtreeOpen() */
36410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36420 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
36430 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
36440 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
36450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36460 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
36470 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
36480 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
36490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
364a0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
364b0 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
364c0 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
364d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
364e0 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
364f0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
36500 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32  nnection {H17002
36510 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H17000>.**.**
36520 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
36530 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36540 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  r the [sqlite3_m
36550 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61  utex] object tha
36560 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73  t .** serializes
36570 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b   access to the [
36580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36590 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68  ion] given in th
365a0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68  e argument.** wh
365b0 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  en the [threadin
365c0 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61  g mode] is Seria
365d0 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  lized..** If the
365e0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
365f0 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] is Single-thre
36600 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65  ad or Multi-thre
36610 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20  ad then this.** 
36620 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
36630 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36640 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
36650 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74   *sqlite3_db_mut
36660 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ex(sqlite3*);../
36670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
36680 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c  ow-Level Control
36690 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c   Of Database Fil
366a0 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30  es {H11300} <S30
366b0 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  800>.**.** {H113
366c0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
366d0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
366e0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
366f0 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74   a direct call t
36700 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f  o the.** xFileCo
36710 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72  ntrol method for
36720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
36730 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
36740 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
36750 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
36760 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69   database identi
36770 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
36780 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31  nd argument. {H1
36790 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d  1302} The.** nam
367a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
367b0 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73  e is the name as
367c0 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61  signed to the da
367d0 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a  tabase by the.**
367e0 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61   <a href="lang_a
367f0 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41  ttach.html">ATTA
36800 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61  CH</a> SQL comma
36810 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74  nd that opened t
36820 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
36830 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74  {H11303} To cont
36840 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74  rol the main dat
36850 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20  abase file, use 
36860 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a  the name "main".
36870 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ** or a NULL poi
36880 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54  nter. {H11304} T
36890 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
368a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
368b0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  o this routine.*
368c0 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72  * are passed dir
368d0 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f  ectly through to
368e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
368f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73  third parameters
36900 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65   of.** the xFile
36910 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
36920 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65   {H11305} The re
36930 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
36940 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a  e xFileControl.*
36950 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73  * method becomes
36960 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36970 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
36980 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36  e..**.** {H11306
36990 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  } If the second 
369a0 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
369b0 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
369c0 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
369d0 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
369e0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
369f0 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
36a00 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37  eturned. {H11307
36a10 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20  } This error.** 
36a20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
36a30 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
36a40 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
36a50 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
36a60 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
36a70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
36a80 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e   {A11308} The un
36a90 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
36aa0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
36ab0 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
36ac0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
36ad0 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20   {A11309} There 
36ae0 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
36af0 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
36b00 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
36b10 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
36b20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
36b30 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
36b40 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
36b50 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
36b60 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
36b70 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
36b80 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
36b90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36ba0 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
36bb0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
36bc0 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
36bd0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
36be0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69   CAPI3REF: Testi
36bf0 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31  ng Interface {H1
36c00 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a  1400} <S30800>.*
36c10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36c20 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20  _test_control() 
36c30 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
36c40 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e  d to read out in
36c50 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20  ternal.** state 
36c60 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f  of SQLite and to
36c70 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69   inject faults i
36c80 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74  nto SQLite for t
36c90 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73  esting.** purpos
36ca0 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  es.  The first p
36cb0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f  arameter is an o
36cc0 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68  peration code th
36cd0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
36ce0 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61   the number, mea
36cf0 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74  ning, and operat
36d00 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65  ion of all subse
36d10 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
36d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
36d30 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f  erface is not fo
36d40 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61  r use by applica
36d50 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74  tions.  It exist
36d60 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20  s solely.** for 
36d70 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f  verifying the co
36d80 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrect operation 
36d90 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
36da0 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e  brary.  Dependin
36db0 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20  g.** on how the 
36dc0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
36dd0 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73  s compiled, this
36de0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
36df0 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a   not exist..**.*
36e00 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
36e10 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63   the operation c
36e20 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e  odes, their mean
36e30 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65  ings, the parame
36e40 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b  ters.** they tak
36e50 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79  e, and what they
36e60 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a   do are all subj
36e70 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
36e80 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a  thout notice..**
36e90 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20   Unlike most of 
36ea0 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20  the SQLite API, 
36eb0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
36ec0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
36ed0 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f  to.** operate co
36ee0 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20  nsistently from 
36ef0 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
36f00 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20  he next..*/.int 
36f10 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
36f20 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e  trol(int op, ...
36f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36f40 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65  EF: Testing Inte
36f50 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20  rface Operation 
36f60 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c  Codes {H11410} <
36f70 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11400>.**.** Th
36f80 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
36f90 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72  e the valid oper
36fa0 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d  ation code param
36fb0 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73  eters used.** as
36fc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36fd0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
36fe0 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e  test_control()].
36ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72  .**.** These par
37000 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69  ameters and thei
37010 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73  r meanings are s
37020 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
37030 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  .** without noti
37040 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65  ce.  These value
37050 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e  s are for testin
37060 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e  g purposes only.
37070 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
37080 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
37090 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72  any of these par
370a0 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a  ameters or the.*
370b0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  * [sqlite3_test_
370c0 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
370d0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
370e0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
370f0 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20  _PRNG_SAVE      
37100 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
37110 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
37120 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45  TRL_PRNG_RESTORE
37130 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
37140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
37150 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45  STCTRL_PRNG_RESE
37160 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
37170 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
37180 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43  _TESTCTRL_BITVEC
37190 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20  _TEST           
371a0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
371b0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55  ITE_TESTCTRL_FAU
371c0 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20  LT_INSTALL      
371d0 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
371e0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
371f0 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f  BENIGN_MALLOC_HO
37200 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69  OKS     10.#defi
37210 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
37220 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20  RL_PENDING_BYTE 
37230 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
37240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
37250 54 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20  TCTRL_ASSERT    
37260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
37270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37280 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20  TESTCTRL_ALWAYS 
37290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
372a0 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
372b0 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 53 45  TE_TESTCTRL_RESE
372c0 52 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20  RVE             
372d0 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
372e0 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20 52  PI3REF: SQLite R
372f0 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20 7b 48  untime Status {H
37300 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  17200} <S60200>.
37310 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
37320 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
37330 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
37340 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65  retrieve runtime
37350 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74   status informat
37360 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ion.** about the
37370 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 20   preformance of 
37380 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 69  SQLite, and opti
37390 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 20  onally to reset 
373a0 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 77  various.** highw
373b0 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 68 65  ater marks.  The
373c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
373d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
373e0 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 70  de for.** the sp
373f0 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 65 72  ecific parameter
37400 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 52 65   to measure.  Re
37410 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 65 72  cognized integer
37420 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f 66   codes.** are of
37430 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49 54   the form [SQLIT
37440 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f  E_STATUS_MEMORY_
37450 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f 53 54  USED | SQLITE_ST
37460 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68  ATUS_...]..** Th
37470 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
37480 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
37490 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 74   is returned int
374a0 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 20  o *pCurrent..** 
374b0 54 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f  The highest reco
374c0 72 64 65 64 20 76 61 6c 75 65 20 69 73 20 72 65  rded value is re
374d0 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67 68  turned in *pHigh
374e0 77 61 74 65 72 2e 20 20 49 66 20 74 68 65 0a 2a  water.  If the.*
374f0 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 74  * resetFlag is t
37500 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69  rue, then the hi
37510 67 68 65 73 74 20 72 65 63 6f 72 64 20 76 61 6c  ghest record val
37520 75 65 20 69 73 20 72 65 73 65 74 20 61 66 74 65  ue is reset afte
37530 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72  r.** *pHighwater
37540 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53 6f 6d   is written. Som
37550 65 20 70 61 72 61 6d 65 74 65 72 73 20 64 6f 20  e parameters do 
37560 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65 20 68  not record the h
37570 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 65 2e  ighest.** value.
37580 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61 72 61    For those para
37590 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e  meters.** nothin
375a0 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  g is written int
375b0 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 6e  o *pHighwater an
375c0 64 20 74 68 65 20 72 65 73 65 74 46 6c 61 67 20  d the resetFlag 
375d0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 4f  is ignored..** O
375e0 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 73 20  ther parameters 
375f0 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65 20  record only the 
37600 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 61  highwater mark a
37610 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72 65  nd not the curre
37620 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f  nt.** value.  Fo
37630 72 20 74 68 65 73 65 20 6c 61 74 74 65 72 20 70  r these latter p
37640 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69 6e  arameters nothin
37650 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  g is written int
37660 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 0a  o *pCurrent..**.
37670 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
37680 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
37690 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  K on success and
376a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b   a non-zero.** [
376b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
376c0 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ailure..**.** Th
376d0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
376e0 72 65 61 64 73 61 66 65 20 62 75 74 20 69 73 20  readsafe but is 
376f0 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 68 69  not atomic.  Thi
37700 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a 2a 2a  s routine can.**
37710 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 6f 74   called while ot
37720 68 65 72 20 74 68 72 65 61 64 73 20 61 72 65 20  her threads are 
37730 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 6d 65  running the same
37740 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20 53 51   or different SQ
37750 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  Lite.** interfac
37760 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74 68 65  es.  However the
37770 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
37780 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e   in *pCurrent an
37790 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72  d.** *pHighwater
377a0 20 72 65 66 6c 65 63 74 20 74 68 65 20 73 74 61   reflect the sta
377b0 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20 61 74  tus of SQLite at
377c0 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69 6e 74   different point
377d0 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e 64  s in time.** and
377e0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20   it is possible 
377f0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
37800 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ead might change
37810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
37820 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65  * in between the
37830 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 43 75   times when *pCu
37840 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 67 68  rrent and *pHigh
37850 77 61 74 65 72 20 61 72 65 20 77 72 69 74 74 65  water are writte
37860 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  n..**.** See als
37870 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  o: [sqlite3_db_s
37880 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49  tatus()].*/.SQLI
37890 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
378a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 61 74  int sqlite3_stat
378b0 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a  us(int op, int *
378c0 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 2a 70  pCurrent, int *p
378d0 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 20 72  Highwater, int r
378e0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a  esetFlag);.../*.
378f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
37900 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 7b  tus Parameters {
37910 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 30 3e  H17250} <H17200>
37920 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
37930 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
37940 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
37950 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f 75 73  esignate various
37960 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 75 73   run-time status
37970 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
37980 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 75 72  hat can be retur
37990 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
379a0 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  status()]..**.**
379b0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
379c0 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52  ITE_STATUS_MEMOR
379d0 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  Y_USED</dt>.** <
379e0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
379f0 72 20 69 73 20 74 68 65 20 63 75 72 72 65 6e 74  r is the current
37a00 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
37a10 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a 2a 2a  y checked out.**
37a20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37a30 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 68 65  malloc()], eithe
37a40 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 69 6e  r directly or in
37a50 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 0a 2a  directly.  The.*
37a60 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 64 65  * figure include
37a70 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 6f 20  s calls made to 
37a80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37a90 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  )] by the applic
37aa0 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 6e 74  ation.** and int
37ab0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 73 61  ernal memory usa
37ac0 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ge by the SQLite
37ad0 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 61 74   library.  Scrat
37ae0 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  ch memory.** con
37af0 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49  trolled by [SQLI
37b00 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
37b10 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 72 79  H] and auxiliary
37b20 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a 20 6d   page-cache.** m
37b30 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c 65 64  emory controlled
37b40 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
37b50 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 69 73  IG_PAGECACHE] is
37b60 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e   not included in
37b70 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d 65 74  .** this paramet
37b80 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e 74 20  er.  The amount 
37b90 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
37ba0 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c 6f 63  sum of the alloc
37bb0 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 20 61  ation.** sizes a
37bc0 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 74 68  s reported by th
37bd0 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 20 69  e xSize method i
37be0 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  n [sqlite3_mem_m
37bf0 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a  ethods].</dd>.**
37c00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
37c10 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a  TATUS_MALLOC_SIZ
37c20 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
37c30 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63  is parameter rec
37c40 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74  ords the largest
37c50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37c60 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61  on request.** ha
37c70 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  nded to [sqlite3
37c80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
37c90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
37ca0 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a 20 69  ] (or their.** i
37cb0 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 6c 65  nternal equivale
37cc0 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 65 20  nts).  Only the 
37cd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
37ce0 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77  n the.** *pHighw
37cf0 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74  ater parameter t
37d00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  o [sqlite3_statu
37d10 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72  s()] is of inter
37d20 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61  est.  .** The va
37d30 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lue written into
37d40 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70   the *pCurrent p
37d50 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65  arameter is unde
37d60 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
37d70 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41  * <dt>SQLITE_STA
37d80 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53  TUS_PAGECACHE_US
37d90 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
37da0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65  his parameter re
37db0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
37dc0 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 20 6f   of pages used o
37dd0 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 61  ut of the.** [pa
37de0 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
37df0 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 20 77  llocator] that w
37e00 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73  as configured us
37e10 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ing .** [SQLITE_
37e20 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
37e30 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c 75 65  ].  The.** value
37e40 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20   returned is in 
37e50 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 62 79  pages, not in by
37e60 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  tes.</dd>.**.** 
37e70 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55  <dt>SQLITE_STATU
37e80 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52  S_PAGECACHE_OVER
37e90 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FLOW</dt>.** <dd
37ea0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
37eb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37ec0 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 70  er of bytes of p
37ed0 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 6c 6c  age cache.** all
37ee0 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f  ocation which co
37ef0 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69  uld not be stati
37f00 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51  sfied by the [SQ
37f10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
37f20 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 65 72  CACHE].** buffer
37f30 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65   and where force
37f40 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f  d to overflow to
37f50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37f60 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 65 74  ()].  The.** ret
37f70 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e 63 6c  urned value incl
37f80 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  udes allocations
37f90 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 64   that overflowed
37fa0 20 62 65 63 61 75 73 65 20 74 68 65 79 0a 2a 2a   because they.**
37fb0 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 67 65   where too large
37fc0 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 72 67   (they were larg
37fd0 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 7a 22  er than the "sz"
37fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
37ff0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
38000 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e 64 20  PAGECACHE]) and 
38010 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74  allocations that
38020 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61   overflowed beca
38030 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 65 20  use.** no space 
38040 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 65 20  was left in the 
38050 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 64 3e  page cache.</dd>
38060 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
38070 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43  E_STATUS_PAGECAC
38080 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  HE_SIZE</dt>.** 
38090 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74  <dd>This paramet
380a0 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  er records the l
380b0 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c  argest memory al
380c0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
380d0 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 70  .** handed to [p
380e0 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  agecache memory 
380f0 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c  allocator].  Onl
38100 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  y the value retu
38110 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a  rned in the.** *
38120 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d  pHighwater param
38130 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
38140 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66  _status()] is of
38150 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20   interest.  .** 
38160 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65  The value writte
38170 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72  n into the *pCur
38180 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69  rent parameter i
38190 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  s undefined.</dd
381a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
381b0 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43  TE_STATUS_SCRATC
381c0 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  H_USED</dt>.** <
381d0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65  dd>This paramete
381e0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  r returns the nu
381f0 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 74 69  mber of allocati
38200 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20  ons used out of 
38210 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 68 20  the.** [scratch 
38220 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
38230 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69  ] configured usi
38240 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  ng.** [SQLITE_CO
38250 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e 20 20  NFIG_SCRATCH].  
38260 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
38270 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 61 74  ed is in allocat
38280 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 6e 20  ions, not.** in 
38290 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 61 20  bytes.  Since a 
382a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 6d 61  single thread ma
382b0 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e 65 20  y only have one 
382c0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
382d0 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  on.** outstandin
382e0 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 73 20  g at time, this 
382f0 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f 20 72  parameter also r
38300 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65  eports the numbe
38310 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a 2a 20  r of threads.** 
38320 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 6d 65  using scratch me
38330 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 6d 65  mory at the same
38340 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   time.</dd>.**.*
38350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41  * <dt>SQLITE_STA
38360 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 52  TUS_SCRATCH_OVER
38370 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FLOW</dt>.** <dd
38380 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  >This parameter 
38390 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
383a0 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 73  er of bytes of s
383b0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a  cratch memory.**
383c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63   allocation whic
383d0 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73  h could not be s
383e0 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68 65  tatisfied by the
383f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
38400 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 66 66  SCRATCH].** buff
38410 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72  er and where for
38420 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20  ced to overflow 
38430 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
38440 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 6c 75  oc()].  The valu
38450 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  es.** returned i
38460 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f 77 73  nclude overflows
38470 20 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71   because the req
38480 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f  uested allocatio
38490 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c 61 72  n was too.** lar
384a0 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 62 65  ger (that is, be
384b0 63 61 75 73 65 20 74 68 65 20 72 65 71 75 65 73  cause the reques
384c0 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77  ted allocation w
384d0 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  as larger than t
384e0 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 61 6d  he.** "sz" param
384f0 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 45 5f  eter to [SQLITE_
38500 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 29  CONFIG_SCRATCH])
38510 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e 6f 20   and because no 
38520 73 63 72 61 74 63 68 20 62 75 66 66 65 72 0a 2a  scratch buffer.*
38530 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 76 61  * slots were ava
38540 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 3e  ilable..** </dd>
38550 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
38560 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48  E_STATUS_SCRATCH
38570 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _SIZE</dt>.** <d
38580 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72  d>This parameter
38590 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72   records the lar
385a0 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  gest memory allo
385b0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a  cation request.*
385c0 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 63 72  * handed to [scr
385d0 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  atch memory allo
385e0 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68  cator].  Only th
385f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
38600 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67   in the.** *pHig
38610 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72  hwater parameter
38620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61   to [sqlite3_sta
38630 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74  tus()] is of int
38640 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20  erest.  .** The 
38650 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e  value written in
38660 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74  to the *pCurrent
38670 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e   parameter is un
38680 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
38690 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53  .** <dt>SQLITE_S
386a0 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41  TATUS_PARSER_STA
386b0 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CK</dt>.** <dd>T
386c0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65  his parameter re
386d0 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 65 73  cords the deepes
386e0 74 20 70 61 72 73 65 72 20 73 74 61 63 6b 2e 20  t parser stack. 
386f0 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d   It is only.** m
38700 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 51 4c  eaningful if SQL
38710 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
38720 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d 41 58  with [YYTRACKMAX
38730 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f 64 64  STACKDEPTH].</dd
38740 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
38750 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 72 61   New status para
38760 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 61 64  meters may be ad
38770 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 74 6f  ded from time to
38780 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e   time..*/.#defin
38790 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  e SQLITE_STATUS_
387a0 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 20 20  MEMORY_USED     
387b0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
387c0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47  QLITE_STATUS_PAG
387d0 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 20 20  ECACHE_USED     
387e0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
387f0 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41  TE_STATUS_PAGECA
38800 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 20 32  CHE_OVERFLOW   2
38810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38820 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55  STATUS_SCRATCH_U
38830 53 45 44 20 20 20 20 20 20 20 20 20 33 0a 23 64  SED         3.#d
38840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
38850 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 52  TUS_SCRATCH