/ Hex Artifact Content
Login

Artifact ea235b37a691b32e7941baa70fb0afaf6377dbb4:


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 30 30 20 32 30 30 38 2f 31  n,v 1.400 2008/1
05f0: 30 2f 30 32 20 31 34 3a 33 33 3a 35 37 20 64 72  0/02 14:33:57 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 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20 69 66  eturn nonzero if
1b10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1b20: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 20 20 20 20   only if.**     
1b30: 20 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20       SQLite was 
1b40: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1b50: 65 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e  e its mutexes en
1b60: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1b70: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d  ..**.** {H10102}
1b80: 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
1b90: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
1ba0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1bb0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  ] function.**   
1bc0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74         shall not
1bd0: 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74   change when mut
1be0: 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d  ex setting are m
1bf0: 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20  odified at.**   
1c00: 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75         runtime u
1c10: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
1c20: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
1c30: 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20  rface and .**   
1c40: 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c         especiall
1c50: 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  y the [SQLITE_CO
1c60: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1c70: 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D],.**          
1c80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1c90: 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51  ULTITHREAD], [SQ
1ca0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
1cb0: 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20  ALIZED],.**     
1cc0: 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45       and [SQLITE
1cd0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76  _CONFIG_MUTEX] v
1ce0: 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  erbs..*/.int sql
1cf0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1d00: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1d10: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
1d20: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
1d30: 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30  le {H12000} <S40
1d40: 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1d50: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
1d60: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
1d70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
1d80: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
1d90: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1da0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1db0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1dc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
1dd0: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
1de0: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
1df0: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
1e00: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
1e10: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
1e20: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
1e30: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
1e40: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1e50: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1e60: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
1e70: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1e80: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
1e90: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
1ea0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1eb0: 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72  .** is its destr
1ec0: 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72  uctor.  There ar
1ed0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74  e many other int
1ee0: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
1ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1f00: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
1f10: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1f20: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
1f30: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1f40: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
1f50: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
1f60: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
1f70: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
1f80: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1f90: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1fa0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
1fb0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1fc0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1fd0: 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e  H10200} <S10110>
1fe0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1ff0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
2000: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
2010: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
2020: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
2030: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
2040: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
2050: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
2060: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
2070: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
2080: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
2090: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
20a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
20b0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
20c0: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
20d0: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66  eferred type def
20e0: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  initions..** The
20f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
2100: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
2110: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72  types are suppor
2120: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
2130: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
2140: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
2150: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2160: 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {H10201} The [s
2170: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
2180: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
2190: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
21a0: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
21b0: 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
21c0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
21d0: 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c  H10202} The [sql
21e0: 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20  ite_uint64] and 
21f0: 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d  [sqlite3_uint64]
2200: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
2210: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
2220: 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
2230: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69  d integer..*/.#i
2240: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
2250: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
2260: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2270: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
2280: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2290: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
22a0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
22b0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
22c0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
22d0: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
22e0: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
22f0: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
2300: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2310: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2320: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2330: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2340: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2350: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2360: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
2370: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2380: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
2390: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
23a0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
23b0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
23c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
23d0: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
23e0: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
23f0: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
2400: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
2410: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2420: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2430: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2440: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2450: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2460: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
2470: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
2480: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
2490: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
24a0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
24b0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
24c0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
24d0: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
24e0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24f0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2500: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2510: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2520: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2530: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2540: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2550: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2560: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2570: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2580: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
2590: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
25a0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
25b0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
25c0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
25d0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
25e0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
25f0: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2600: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2610: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2620: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2630: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2640: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2650: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
2660: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
2670: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
2680: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
2690: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
26a0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
26b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
26c0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
26d0: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
26e0: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
26f0: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2700: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2710: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2720: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2730: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2740: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2750: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
2760: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2770: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2780: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2790: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
27a0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
27b0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
27c0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
27d0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
27e0: 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73  12011} A success
27f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2800: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2810: 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65  hall destroy the
2820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
2830: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2840: 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a  n] object C..**.
2850: 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75  ** {H12012} A su
2860: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2870: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2880: 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  C)] shall return
2890: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a   SQLITE_OK..**.*
28a0: 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63  * {H12013} A suc
28b0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
28c0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
28d0: 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65  )] shall release
28e0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
28f0: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74   memory and syst
2900: 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73  em resources ass
2910: 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61  ociated with [da
2920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2930: 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  n].**          C
2940: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d  ..**.** {H12014}
2950: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
2960: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e  te3_close(C)] on
2970: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2980: 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a  nection] C that.
2990: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20  **          has 
29a0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e  one or more open
29b0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29c0: 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69  ments] shall fai
29d0: 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
29e0: 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55     an [SQLITE_BU
29f0: 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a  SY] error code..
2a00: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41  **.** {H12015} A
2a10: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a20: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72  3_close(C)] wher
2a30: 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  e C is a NULL po
2a40: 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20  inter shall.**  
2a50: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53          return S
2a60: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
2a70: 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73  {H12019} When [s
2a80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
2a90: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
2aa0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ab0: 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20  ction] C.**     
2ac0: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20       that has a 
2ad0: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74  pending transact
2ae0: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63  ion, the transac
2af0: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  tion shall be.**
2b00: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64            rolled
2b10: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53   back..**.** ASS
2b20: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
2b30: 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70  {A12016} The C p
2b40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2b50: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
2b60: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
2b70: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
2b80: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
2b90: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2ba0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
2bb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
2bc0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
2bd0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2be0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  n16()], or.**   
2bf0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2c00: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2c10: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
2c20: 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  losed..*/.int sq
2c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
2c40: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
2c50: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
2c60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
2c70: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
2c80: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
2c90: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
2ca0: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
2cb0: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
2cc0: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
2cd0: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
2ce0: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
2cf0: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
2d00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
2d10: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
2d20: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
2d30: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
2d40: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32  n Interface {H12
2d50: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  100} <S10000>.**
2d60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d70: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2d80: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74   is a convenient
2d90: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20   way of running 
2da0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53  one or more.** S
2db0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69  QL statements wi
2dc0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
2dd0: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43  write a lot of C
2de0: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d   code.  The UTF-
2df0: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c  8 encoded.** SQL
2e00: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2e10: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2e20: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e30: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
2e40: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74  c()..** The stat
2e50: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2e60: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20  ated one by one 
2e70: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2e80: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69  error or.** an i
2e90: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f  nterrupt is enco
2ea0: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69  untered, or unti
2eb0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64  l they are all d
2ec0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61  one.  The 3rd pa
2ed0: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e  rameter.** is an
2ee0: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61   optional callba
2ef0: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ck that is invok
2f00: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2f10: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72   row of any quer
2f20: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f  y.** results pro
2f30: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c  duced by the SQL
2f40: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
2f50: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2f60: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74  tells where.** t
2f70: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f  o write any erro
2f80: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a  r messages..**.*
2f90: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * The error mess
2fa0: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20  age passed back 
2fb0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2fc0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c  parameter is hel
2fd0: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  d.** in memory o
2fe0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ff0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
3000: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d    To avoid a mem
3010: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65  ory leak,.** the
3020: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61   calling applica
3030: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c  tion should call
3040: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3050: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a  ] on any error.*
3060: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  * message return
3070: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3080: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65  th parameter whe
3090: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
30a0: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65  d using.** the e
30b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
30c0: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
30d0: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
30e0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  2nd parameter is
30f0: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
3100: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61  y string.** or a
3110: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
3120: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ng only whitespa
3130: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c  ce and comments,
3140: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20   then no SQL.** 
3150: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3160: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3170: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
3180: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3190: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
31a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
31b0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
31c0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
31d0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
31e0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
31f0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3200: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
3210: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
3220: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
3230: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65  s nothing to the
3240: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63   database that c
3250: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
3260: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
3270: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3280: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
3290: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
32a0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ize()]..**.** IN
32b0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32c0: 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 65  {H12101} A succe
32d0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
32e0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32f0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a  c(D,S,C,A,E)].**
3300: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
3310: 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61  sequentially eva
3320: 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65  luate all of the
3330: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3340: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69  **          semi
3350: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
3360: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
3370: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
3380: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
3390: 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69    string S withi
33a0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
33b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
33d0: 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20  .** {H12102} If 
33e0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
33f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3400: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20  (D,S,C,A,E)] is 
3410: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3420: 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e        the action
3430: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61  s of the interfa
3440: 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  ce shall be the 
3450: 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a  same as if the.*
3460: 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72  *          S par
3470: 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65  ameter were an e
3480: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
3490: 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20  ** {H12104} The 
34a0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34b0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
34c0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54   shall be [SQLIT
34d0: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20  E_OK] if all.** 
34e0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
34f0: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
3500: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20  essfully and to 
3510: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
3520: 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72  * {H12105} The r
3530: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
3540: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3550: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72  shall be an appr
3560: 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20  opriate.**      
3570: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72      non-zero [er
3580: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
3590: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
35a0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ails..**.** {H12
35b0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
35c0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
35d0: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
35e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
35f0: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3600: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
3610: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
3620: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
3630: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
3640: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
3650: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
3660: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
3670: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
3680: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3690: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
36a0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  ach row of resul
36b0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30  t..**.** {H12110
36c0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  } If the callbac
36d0: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
36e0: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
36f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3700: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3710: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c  ll abort the SQL
3720: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73   statement it is
3730: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75   currently evalu
3740: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20  ating,.**       
3750: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73     skip all subs
3760: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3770: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72  ments, and retur
3780: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  n [SQLITE_ABORT]
3790: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d  ..**.** {H12113}
37a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
37b0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
37c0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68  all pass its 4th
37d0: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75   parameter throu
37e0: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  gh.**          a
37f0: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  s the 1st parame
3800: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ter of the callb
3810: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ack..**.** {H121
3820: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  16} The [sqlite3
3830: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3840: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32   shall set the 2
3850: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
3860: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3870: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74  callback to be t
3880: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
3890: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72  umns in the curr
38a0: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  ent row of.**   
38b0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a         result..*
38c0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68  *.** {H12119} Th
38d0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
38e0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
38f0: 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72   set the 3rd par
3900: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3910: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3920: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3930: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3940: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3950: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3960: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3970: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3980: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3990: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
39a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
39b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
39c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
39d0: 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b  * {H12122} The [
39e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
39f0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3a00: 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  t the 4th parame
3a10: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3a20: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
3a30: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f  to be an array o
3a40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3a50: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
3a60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  e.**          na
3a70: 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  mes of result co
3a80: 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65  lumns as obtaine
3a90: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
3aa0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ab0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49  **.** {H12125} I
3ac0: 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
3ad0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3ae0: 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20  exec()] is NULL 
3af0: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
3b00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3b10: 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79  ] shall silently
3b20: 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72   discard query r
3b30: 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  esults..**.** {H
3b40: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
3b50: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3b60: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
3b70: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
3b80: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
3b90: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
3ba0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f  he S parameter o
3bb0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
3bc0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20  D,S,C,A,E)] and 
3bd0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
3be0: 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69  he E parameter i
3bf0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3c00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3c10: 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a  ] shall store.**
3c20: 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20            in *E 
3c30: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
3c40: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69  rror message wri
3c50: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
3c60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
3c70: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
3c80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
3c90: 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68  *.** {H12134} Th
3ca0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3cb0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74  D,S,C,A,E)] rout
3cc0: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3cd0: 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  e value of.**   
3ce0: 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c         *E to NUL
3cf0: 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55  L if E is not NU
3d00: 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65  LL and there are
3d10: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a   no errors..**.*
3d20: 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b  * {H12137} The [
3d30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3d40: 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f  ,C,A,E)] functio
3d50: 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  n shall set the 
3d60: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
3d70: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
3d80: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
3d90: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
3da0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
3db0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
3dc0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
3dd0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3de0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38  ]..**.** {H12138
3df0: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3e00: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3e10: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3e20: 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a  ] is NULL or an.
3e30: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74  **          empt
3e40: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74  y string or cont
3e50: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
3e60: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
3e70: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a  ce, comments,.**
3e80: 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72            and/or
3e90: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
3ea0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
3eb0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3ec0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3ed0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3ee0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3ef0: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3f00: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3f10: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3f20: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3f30: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
3f40: 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20  ** {A12141} The 
3f50: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
3f60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3f70: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
3f80: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
3f90: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
3fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3fb0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20  .**.** {A12142} 
3fc0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
3fd0: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3fe0: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3ff0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
4000: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
4010: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
4020: 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {A12143} The cal
4030: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
4040: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
4050: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
4060: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
4070: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
4080: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
4090: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
40a0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
40b0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
40c0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
40d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d  ..**.** {A12145}
40e0: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
40f0: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
4100: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4110: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
4120: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
4130: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
4140: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
4150: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
4160: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
4170: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
4180: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
41b0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
41c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
41f0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
4200: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
4210: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
4220: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
4230: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
4240: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
4250: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
4260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4270: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
4280: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
4290: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
42a0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
42d0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
42e0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
42f0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4300: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
4310: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
4320: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
4330: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
4340: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4350: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
43e0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
43f0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
4400: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
4410: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
4420: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
4430: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
4440: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
4450: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
4460: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
4470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4480: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4490: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
44a0: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
44b0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
44c0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
44d0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
44e0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
44f0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
4500: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4510: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4520: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4530: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4540: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4560: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4570: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4580: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
45a0: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
45b0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
45c0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
45d0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
45e0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
45f0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
4600: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4610: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4620: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4630: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4640: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4650: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4680: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4690: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
46a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
46b0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
46c0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
46d0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
46e0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46f0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
4700: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4710: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4720: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4730: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4740: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4750: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4760: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4770: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
47a0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
47b0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
47c0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
47d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
47e0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
47f0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
4800: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
4810: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
4820: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4830: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4840: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4850: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4860: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4880: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4890: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
48a0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
48b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
48c0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
48d0: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
48e0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
48f0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4900: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4910: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4920: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4930: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4940: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4950: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4960: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4970: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4980: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4990: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
49a0: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
49b0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
49c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
49d0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
49e0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
49f0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
4a00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a10: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4a20: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4a30: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4a50: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4a60: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4a70: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4a80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4a90: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4aa0: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
4ab0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
4ac0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
4ad0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
4ae0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
4af0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4b20: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4b30: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4b40: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4b50: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4b60: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4b70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4b80: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4b90: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
4bb0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
4bc0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
4bd0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
4be0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4bf0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4c00: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4c10: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4c20: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4c30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4c40: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4c50: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4c60: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
4c70: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
4c80: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
4c90: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
4ca0: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4cb0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
4cc0: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
4cd0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
4ce0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4cf0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4d00: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4d10: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4d20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4d30: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4d40: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4d50: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4d60: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4d70: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4d80: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4d90: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4da0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4db0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4dc0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4dd0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4de0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4df0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4e00: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4e10: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4e20: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4e30: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4e40: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4e50: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e60: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e70: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e80: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4e90: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4ea0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4eb0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4ec0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ed0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4ee0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4ef0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4f00: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4f10: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4f20: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4f30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4fb0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4fc0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4fd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4fe0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4ff0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
5000: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
5010: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
5020: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
5030: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
5040: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
5050: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
5060: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
5070: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
5080: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
5090: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
50a0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
50b0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
50c0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
50d0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
50e0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
50f0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
5100: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
5110: 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o..**.** INVARIA
5120: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  NTS:.**.** {H102
5130: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63  23} The symbolic
5140: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74   name for an ext
5150: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
5160: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73  e shall contains
5170: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
5180: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72  elated primary r
5190: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20  esult code as a 
51a0: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48  prefix..**.** {H
51b0: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72  10224} Primary r
51c0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
51d0: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61   shall contain a
51e0: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72   single "_" char
51f0: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  acter..**.** {H1
5200: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72  0225} Extended r
5210: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
5220: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74   shall contain t
5230: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63  wo or more "_" c
5240: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
5250: 20 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75   {H10226} The nu
5260: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61  meric value of a
5270: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
5280: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e  t code shall con
5290: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  tain the.**     
52a0: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c       numeric val
52b0: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73  ue of its corres
52c0: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
52d0: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a  result code in.*
52e0: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c  *          its l
52f0: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
5300: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66   8 bits..*/.#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5350: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5360: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5370: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5380: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5390: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
53a0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
53b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53c0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
53d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
53e0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
53f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5400: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5420: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5440: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5460: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5480: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
54c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54d0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
54e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5500: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5510: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5520: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5530: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5550: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5560: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5590: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
55a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
55c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55d0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
55e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5600: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5610: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5620: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5630: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5650: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5660: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5670: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5690: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
56a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
56c0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
56d0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
56e0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
56f0: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31  ns {H10230} <H11
5700: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a  120> <H12700>.**
5710: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5720: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5730: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5740: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5750: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5760: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5770: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5780: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5790: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  er to the xOpen 
57a0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a  method of the.**
57b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
57c0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
57d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
57e0: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
57f0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5800: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
5810: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
5820: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5830: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
5840: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
5850: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
5860: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
5870: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
5880: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5890: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
58a0: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
58b0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
58c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
58d0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
58e0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
58f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
5900: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
5910: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5920: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
5930: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
5940: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5950: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
5960: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
5970: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
5980: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
5990: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
59a0: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
59b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
59c0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
59d0: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e  x00002000.#defin
59e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
59f0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
5a00: 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e  x00004000.#defin
5a10: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
5a20: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
5a30: 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e  x00008000.#defin
5a40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
5a50: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
5a60: 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00010000../*.**
5a70: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
5a80: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
5a90: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31  s {H10240} <H111
5aa0: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  20>.**.** The xD
5ab0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
5ac0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
5ad0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5ae0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
5af0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
5b00: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
5b10: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
5b20: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
5b30: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
5b40: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
5b50: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
5b60: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
5b70: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
5b80: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
5b90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
5ba0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
5bb0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
5bc0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
5bd0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
5be0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
5bf0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
5c00: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5c10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
5c20: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
5c30: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
5c40: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
5c50: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
5c60: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
5c70: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
5c80: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
5c90: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
5ca0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
5cb0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5cc0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5cd0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
5ce0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
5cf0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
5d00: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
5d10: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
5d20: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
5d30: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
5d40: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
5d50: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
5d60: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
5d70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5d80: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
5d90: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
5da0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
5db0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
5dc0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
5dd0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5de0: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
5df0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e00: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
5e10: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e30: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
5e40: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e60: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5e70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5ea0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ec0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5ed0: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ef0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5f00: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f20: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5f30: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f50: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
5f60: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5f70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f80: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5f90: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5fa0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5fb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5fc0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
5fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5fe0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5ff0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
6000: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6010: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6020: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32   {H10250} <H1112
6030: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a  0> <H11310>.**.*
6040: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6050: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6060: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6070: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6080: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6090: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
60a0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
60b0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
60c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
60d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
60e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
60f0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6100: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6110: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6120: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6130: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6140: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6160: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6170: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6180: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6190: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
61a0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
61b0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
61c0: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31  ags {H10260} <H1
61d0: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  1120>.**.** When
61e0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
61f0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6200: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6210: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6220: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6230: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6240: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6250: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6260: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6290: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
62a0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
62b0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
62c0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
62d0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
62e0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
62f0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6300: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6310: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
6320: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6330: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  AL flag means.**
6340: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6350: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6360: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
6370: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
6380: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
6390: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
63a0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
63b0: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  sync()..*/.#defi
63c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
63d0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
63e0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
63f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
6400: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
6410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6420: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
6430: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
6440: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6450: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
6460: 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d   Handle {H11110}
6470: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
6480: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6490: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
64a0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
64b0: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
64c0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
64d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
64e0: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
64f0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
6500: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
6510: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
6520: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
6530: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6540: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6550: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6560: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6570: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6580: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6590: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
65a0: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
65b0: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
65c0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
65d0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
65e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
65f0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
6610: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
6620: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
6630: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6640: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6650: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6660: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6670: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6680: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6690: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
66a0: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31  thods Object {H1
66b0: 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1120} <S20110>.*
66c0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
66d0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
66e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65  qlite3_vfs] xOpe
66f0: 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  n method populat
6700: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
6710: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
6720: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
6730: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
6740: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6750: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
6760: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
6770: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
6780: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
6790: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
67a0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
67b0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
67c0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
67d0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
67e0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
67f0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
6800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6810: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
6820: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6830: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6840: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6850: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6860: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6870: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6880: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6890: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
68a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
68b0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58  ce is a Mac OS-X
68c0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
68d0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
68e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
68f0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6900: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6910: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6920: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6930: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6940: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6950: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6960: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6970: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6980: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6990: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
69a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
69b0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
69c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
69d0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
69e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
69f0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6a00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6a10: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6a20: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6a30: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6a40: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6a50: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6a60: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6a70: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6a80: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6a90: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6aa0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6ab0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6ac0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6ad0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ae0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6af0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6b00: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6b10: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6b20: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6b30: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6b40: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6b50: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6b60: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6b70: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6b80: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6b90: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6ba0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6bb0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6bc0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6bd0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6be0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6bf0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6c00: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6c10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6c20: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6c30: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6c40: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6c50: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6c60: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6c70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6c80: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6c90: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6ca0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6cb0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6cc0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6cd0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6ce0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6cf0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6d00: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6d10: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6d20: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6d30: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6d40: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6d50: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6d60: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6d70: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6d80: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6d90: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6da0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6db0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6dc0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6dd0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6de0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6df0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6e00: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6e10: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6e20: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6e30: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6e40: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6e50: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6e60: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6e70: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6e80: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6e90: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6ea0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6eb0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6ec0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6ed0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6ee0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a  id conflicts..**
6ef0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
6f00: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
6f10: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
6f20: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
6f30: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
6f40: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
6f50: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
6f60: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
6f70: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
6f80: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
6f90: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
6fa0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
6fb0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
6fc0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6fd0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
6fe0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
6ff0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7000: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7010: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7020: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7030: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7040: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7050: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7070: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7090: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
70a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
70c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
70e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7110: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7140: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7150: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7170: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7180: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7190: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
71a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
71b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
71c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
71d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
71e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
71f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7200: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7210: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7220: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7230: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7240: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7250: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7260: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7270: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7280: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7290: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
72a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
72b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
72c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
72d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
72e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
72f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7300: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7310: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7320: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7330: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7340: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7350: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7360: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7370: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7380: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7390: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
73a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
73b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
73c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
73d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
73e0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
73f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7400: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
7410: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
7420: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
7430: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
7440: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
7450: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
7460: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7470: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
7480: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
7490: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
74a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
74b0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
74c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
74d0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
74e0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
74f0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7500: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
7510: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
7520: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
7530: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
7540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7550: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
7560: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
7570: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7580: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
7590: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
75a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
75b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
75c0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
75d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
75e0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
75f0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
7600: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
7610: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
7620: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
7630: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7640: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
7650: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
7660: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
7670: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7680: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7690: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
76a0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69  ile*);.  /* Addi
76b0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
76c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
76d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
76e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
76f0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
7700: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
7710: 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33  des {H11310} <S3
7720: 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0800>.**.** Thes
7730: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
7740: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
7750: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
7760: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
7770: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
7780: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7790: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
77a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
77b0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
77c0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
77d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
77e0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
77f0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
7800: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
7810: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
7820: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7830: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
7840: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
7850: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
7860: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
7870: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
7880: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
7890: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
78a0: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
78b0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
78c0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
78d0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
78e0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
78f0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
7900: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
7910: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
7920: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
7930: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
7940: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
7950: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
7960: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
7970: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a   is defined..*/.
7980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
7990: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
79a0: 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43        1../*.** C
79b0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
79c0: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c  andle {H17110} <
79d0: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20130>.**.** Th
79e0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
79f0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
7a00: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
7a10: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
7a20: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
7a30: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
7a40: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
7a50: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
7a60: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
7a70: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
7a80: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
7a90: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
7aa0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
7ab0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
7ac0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
7ad0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
7ae0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
7af0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
7b00: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
7b10: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7b20: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
7b30: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
7b40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7b50: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
7b60: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53  ject {H11140} <S
7b70: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20100>.**.** An 
7b80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7b90: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7ba0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7bb0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7bc0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7bd0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7be0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
7bf0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
7c00: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
7c10: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
7c20: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
7c30: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
7c40: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
7c50: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
7c60: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
7c70: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
7c80: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
7c90: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
7ca0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
7cb0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
7cc0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
7cd0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
7ce0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
7cf0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
7d00: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
7d10: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
7d20: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
7d30: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
7d40: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
7d50: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
7d60: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
7d70: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
7d80: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
7d90: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
7da0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
7db0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
7dc0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
7dd0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
7de0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
7df0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
7e00: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
7e10: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7e20: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7e30: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7e40: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7e50: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7e60: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7e70: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7e80: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7e90: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7ea0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7eb0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
7ec0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
7ed0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
7ee0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
7ef0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
7f00: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
7f10: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7f20: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7f30: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7f40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7f50: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7f60: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7f70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7f80: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7f90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7fa0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7fb0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
7fc0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
7fd0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
7fe0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
7ff0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8000: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8010: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8020: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8030: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8040: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8050: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8060: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8070: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8080: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8090: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
80a0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
80b0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
80c0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
80d0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
80e0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
80f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8100: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8110: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8120: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8130: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8140: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8150: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8160: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53  **.** {H11141} S
8170: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
8180: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
8190: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
81a0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
81b0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
81c0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
81d0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
81e0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
81f0: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68  ).  SQLite furth
8200: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
8210: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
8220: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
8230: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
8240: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
8250: 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20  * called. {END} 
8260: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
8270: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73  previous sentens
8280: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
8290: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
82a0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
82b0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
82c0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
82d0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
82e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
82f0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
8300: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
8310: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
8320: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
8330: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
8340: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20  .** must invite 
8350: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
8360: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
8370: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
8380: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8390: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
83a0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
83b0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
83c0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
83d0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
83e0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
83f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8400: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d  ..**.** {H11142}
8410: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8420: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
8430: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
8440: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
8450: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
8470: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
8480: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
8490: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
84a0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
84b0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
84c0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
84d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
84e0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
84f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
8500: 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65  {END}.** If xOpe
8510: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
8520: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
8530: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
8540: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
8550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8560: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
8570: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
8580: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
8590: 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51  *.** {H11143} SQ
85a0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
85b0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
85c0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
85d0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
85e0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
85f0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
8600: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
8610: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
8620: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
8630: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
8640: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8650: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8660: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8670: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
8680: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8690: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
86a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
86b0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
86e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
86f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
8700: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
8710: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
8720: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8730: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8740: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8750: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8760: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8770: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8780: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8790: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
87a0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
87b0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
87c0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
87d0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
87e0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
87f0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
8800: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8810: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8820: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8830: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8840: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8850: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8860: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8870: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8880: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8890: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
88a0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
88b0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
88c0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
88d0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
88e0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
88f0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
8900: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8910: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8920: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8930: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8940: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8950: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8960: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8970: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8980: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
89a0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
89b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
89c0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
89d0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54  **.** {H11145} T
89e0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
89f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
8a00: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
8a10: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
8a20: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
8a30: 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31  is closed.  {H11
8a40: 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  146} The [SQLITE
8a50: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8a60: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
8a70: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61  set for TEMP  da
8a80: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c  tabases, journal
8a90: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75  s and for subjou
8aa0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rnals..**.** {H1
8ab0: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
8ac0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8ad0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
8ae0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
8af0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
8b00: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
8b10: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
8b20: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
8b30: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
8b40: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
8b50: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  file..**.** {H11
8b60: 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a  148} At least sz
8b70: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
8b80: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
8b90: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
8ba0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
8bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
8bc0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
8bd0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
8be0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8bf0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70  . {END}  The xOp
8c00: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
8c10: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
8c20: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
8c30: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
8c40: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
8c50: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20  .**.** {H11149} 
8c60: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
8c70: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
8c80: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
8c90: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
8ca0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
8cb0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
8cc0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
8cd0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8ce0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
8cf0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8d00: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
8d10: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
8d20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
8d30: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
8d40: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
8d50: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b  east readable. {
8d60: 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63  END}  The file c
8d70: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
8d80: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  tory..**.** {H11
8d90: 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  150} SQLite will
8da0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
8db0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
8dc0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
8dd0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
8de0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
8df0: 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68  ame. {H11151} Th
8e00: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
8e10: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8e20: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
8e30: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
8e40: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
8e50: 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74  ods. {END}  If t
8e60: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
8e70: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
8e80: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
8e90: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
8ea0: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
8eb0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
8ec0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
8ed0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
8ee0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
8ef0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
8f00: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
8f10: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
8f20: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
8f30: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
8f40: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
8f50: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
8f60: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
8f70: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
8f80: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
8f90: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
8fa0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
8fb0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
8fc0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
8fd0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
8fe0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
8ff0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
9000: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9010: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
9020: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
9030: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
9040: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
9050: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
9060: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
9070: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
9080: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
9090: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
90a0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
90b0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
90c0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
90d0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
90e0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
90f0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
9100: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
9110: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
9120: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
9130: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
9140: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
9150: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
9160: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
9170: 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  time..*/.typedef
9180: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9190: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
91a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
91b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
91c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
91d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
91e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
91f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9200: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9210: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9220: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9230: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9240: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9250: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9260: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9270: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9280: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9290: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
92a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
92b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
92c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
92d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
92e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
92f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9300: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9310: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9320: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9330: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9340: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9350: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9360: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9370: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9380: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9390: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
93a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
93b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
93c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
93d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
93e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
93f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9400: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9410: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9420: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9430: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9440: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9450: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9460: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9470: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9480: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9490: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
94a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
94b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
94e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Msg);.  void *(*
94f0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
9500: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
9510: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
9520: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
9530: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
9540: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
9550: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
9560: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9570: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
9580: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
9590: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
95a0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
95b0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
95c0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
95d0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
95e0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
95f0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
9600: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
9610: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  har *);.  /* New
9620: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
9630: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
9640: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
9650: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
9660: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
9670: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
9680: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
9690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
96a0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
96b0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
96c0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31  od {H11190} <H11
96d0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  140>.**.** {H111
96e0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
96f0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
9700: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
9710: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
9720: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
9730: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
9740: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
9750: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
9760: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
9770: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
9780: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
9790: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
97a0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31  ing for..** {H11
97b0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
97c0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
97d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
97e0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
97f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9800: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
9810: 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51  {H11193} With SQ
9820: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9830: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
9840: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9850: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9860: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
9870: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
9880: 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20  le..** {H11194} 
9890: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
98a0: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
98b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
98c0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
98d0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
98e0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
98f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9900: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
9910: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9920: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
9930: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9940: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
9950: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
9960: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
9970: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30  ite Library {H10
9980: 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  130} <S20000><S3
9990: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
99a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
99b0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
99c0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
99d0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
99e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
99f0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
9a00: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
9a10: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
9a20: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
9a30: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
9a40: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  ialize()..**.** 
9a50: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
9a60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9a70: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
9a80: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
9a90: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
9aa0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ab0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
9ac0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
9ad0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
9ae0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
9af0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
9b00: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9b10: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9b20: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
9b30: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
9b40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f  3_shutdown().  O
9b50: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
9b60: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
9b70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9b80: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
9b90: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
9ba0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
9bb0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
9bc0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  s..**.** Among o
9bd0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
9be0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9bf0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
9c00: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
9c10: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
9c20: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9c30: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
9c40: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9c50: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9c60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c70: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9c80: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
9c90: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66  n success..** If
9ca0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
9cb0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9cc0: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
9cd0: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
9ce0: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
9cf0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
9d00: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
9d10: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
9d20: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
9d30: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
9d40: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
9d50: 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49   other than SQLI
9d60: 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  TE_OK..**.** The
9d70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9d80: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
9d90: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
9da0: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
9db0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
9dc0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
9dd0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
9de0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
9df0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
9e00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9e10: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
9e20: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
9e30: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
9e40: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
9e50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
9e60: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
9e70: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
9e80: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
9e90: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
9ea0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
9eb0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
9ec0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
9ed0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
9ee0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
9ef0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9f00: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
9f10: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a  OMIT_AUTOINIT.**
9f20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
9f30: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
9f40: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
9f50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
9f60: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
9f70: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
9f80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
9f90: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
9fa0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9fb0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
9fc0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
9fd0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
9fe0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
9ff0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
a000: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
a010: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
a020: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
a030: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a040: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
a050: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a060: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a070: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
a080: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
a090: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
a0a0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
a0b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
a0c0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
a0d0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
a0e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
a0f0: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  th SQLITE_OMIT_A
a100: 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65  UTOINIT might be
a110: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
a120: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
a130: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
a140: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
a150: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a160: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
a170: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
a180: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
a190: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
a1a0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
a1b0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
a1c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a1d0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
a1e0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
a1f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a200: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
a210: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
a220: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
a230: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
a240: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
a250: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
a260: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
a270: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
a280: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
a290: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
a2a0: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
a2b0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
a2c0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
a2d0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
a2e0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
a2f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
a300: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
a310: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
a320: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
a330: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
a340: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
a350: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
a360: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
a370: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
a380: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
a390: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a3a0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
a3b0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
a3c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a3d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
a3e0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
a3f0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
a400: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a410: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
a420: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
a430: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
a440: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
a450: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
a460: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
a470: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a480: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a490: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
a4a0: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
a4b0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
a4c0: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
a4d0: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
a4e0: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
a4f0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
a500: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
a510: 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c  S_OTHER=1 compil
a520: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
a530: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
a540: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
a550: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
a560: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
a570: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a580: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a590: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
a5a0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
a5b0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a5c0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
a5d0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
a5e0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
a5f0: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
a600: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
a610: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a620: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a630: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a640: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a650: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a660: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a670: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a680: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a690: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a6a0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a6b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a6c0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a6d0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a6e0: 31 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c  10145} <S20000><
a6f0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a700: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a710: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a720: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a730: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a740: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a750: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a760: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a770: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a780: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a790: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a7a0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a7b0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a7c0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a7d0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a7e0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a7f0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a800: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a810: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a820: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a830: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a840: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a850: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a860: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a870: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a880: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a890: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a8a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a8b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a8c0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a8d0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a8e0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a8f0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a910: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
a920: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
a930: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
a940: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
a950: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
a960: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
a970: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
a980: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a990: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
a9a0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
a9b0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
a9c0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
a9d0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
a9e0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
a9f0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aa00: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
aa10: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
aa20: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
aa30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
aa40: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
aa50: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
aa60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
aa80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
aa90: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
aaa0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aab0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
aac0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
aad0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
aae0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
aaf0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
ab00: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ab10: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ab20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ab30: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ab40: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ab50: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ab60: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ab70: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ab80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ab90: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
aba0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
abb0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
abc0: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
abd0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
abe0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
abf0: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ac00: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
ac10: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
ac20: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
ac30: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
ac40: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
ac50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
ac60: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
ac70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
ac80: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
ac90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48   connections  {H
aca0: 31 30 31 38 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10180} <S20000>.
acb0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
acc0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
acd0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
ace0: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
acf0: 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
ad00: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ad10: 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
ad20: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
ad30: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
ad40: 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
ad50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ad60: 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
ad70: 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
ad80: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
ad90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ada0: 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
adb0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
adc0: 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71  ent).  The.** sq
add0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
ade0: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
adf0: 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d  only be used imm
ae00: 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a  ediately after.*
ae10: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
ae20: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65  onnection is cre
ae30: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
ae40: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20  te3_open()],.** 
ae50: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
ae60: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
ae70: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a  open_v2()].  .**
ae80: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
ae90: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
aea0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
aeb0: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
aec0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
aed0: 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  erb - an integer
aee0: 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63   code that indic
aef0: 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70  ates what.** asp
af00: 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
af10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
af20: 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
af30: 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c  ured..** The onl
af40: 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69  y choice for thi
af50: 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49  s value is [SQLI
af60: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
af70: 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76  ASIDE]..** New v
af80: 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  erbs are likely 
af90: 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  to be added in f
afa0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
afb0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64  f SQLite..** Add
afc0: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
afd0: 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20  s depend on the 
afe0: 76 65 72 62 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  verb..*/.SQLITE_
aff0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
b000: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b010: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
b020: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
b030: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
b040: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
b050: 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20  utines {H10155} 
b060: 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45  <S20120>.** EXPE
b070: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
b080: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b090: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b0a0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b0b0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b0c0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b0d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b0e0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b0f0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b100: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b110: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b120: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b130: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b140: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b150: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b160: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b170: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b180: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b190: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b1a0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b1b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
b1c0: 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e    By creating an
b1d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
b1e0: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
b1f0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
b200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b210: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
b220: 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70  ation, an.** app
b230: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
b240: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
b250: 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ive memory alloc
b260: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a  ation subsystem.
b270: 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  ** for SQLite to
b280: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
b290: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
b2a0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
b2b0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
b2c0: 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75   comes with a bu
b2d0: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
b2e0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a  locator that is.
b2f0: 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  ** perfectly ade
b300: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
b310: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
b320: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
b330: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
b340: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
b350: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
b360: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
b370: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
b380: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
b390: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
b3a0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
b3b0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
b3c0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
b3d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
b3e0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
b3f0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
b400: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
b410: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
b420: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
b430: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
b440: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
b450: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
b460: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
b470: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
b480: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
b490: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
b4a0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
b4b0: 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c  xFree, and xReal
b4c0: 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  loc methods must
b4d0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
b4e0: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65  * malloc(), free
b4f0: 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28  (), and realloc(
b500: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
b510: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
b520: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  brary..**.** xSi
b530: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
b540: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
b550: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
b560: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
b570: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
b580: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
b590: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
b5a0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
b5b0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
b5c0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
b5d0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
b5e0: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
b5f0: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
b600: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
b610: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
b620: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
b630: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
b640: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b650: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
b660: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
b670: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
b680: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
b690: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
b6a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
b6b0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
b6c0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
b6d0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
b6e0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
b6f0: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
b700: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
b710: 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   of 2..**.** The
b720: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
b730: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
b740: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
b750: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
b760: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
b770: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
b780: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
b790: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
b7a0: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
b7b0: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
b7c0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
b7d0: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
b7e0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
b7f0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
b800: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
b810: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
b820: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
b830: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
b840: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
b850: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
b860: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
b870: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
b880: 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  own..*/.typedef 
b890: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b8a0: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
b8b0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
b8c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b8d0: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
b8e0: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
b8f0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
b900: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
b910: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
b920: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
b930: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b940: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
b950: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
b960: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
b970: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
b980: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
b990: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
b9a0: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
b9b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
b9c0: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
b9d0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
b9e0: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
b9f0: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
ba00: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
ba10: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
ba20: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
ba30: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
ba40: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
ba50: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
ba60: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ba70: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ba80: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
ba90: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
baa0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
bab0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
bac0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
bad0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
bae0: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
baf0: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
bb00: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
bb10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bb20: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
bb30: 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20  ptions {H10160} 
bb40: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20000>.** EXPE
bb50: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
bb60: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
bb70: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
bb80: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
bb90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
bba0: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
bbb0: 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
bbc0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
bbd0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
bbe0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
bbf0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
bc00: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
bc10: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
bc20: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
bc30: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
bc40: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
bc50: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
bc60: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
bc70: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
bc80: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
bc90: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
bca0: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
bcb0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
bcc0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
bcd0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
bce0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
bcf0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
bd00: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
bd10: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
bd20: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
bd30: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
bd40: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
bd50: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
bd60: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
bd70: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
bd80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
bd90: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
bda0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bdb0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bdc0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bdd0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bde0: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
bdf0: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
be00: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
be10: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
be20: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
be30: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
be40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
be50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
be60: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
be70: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
be80: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
be90: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
bea0: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
beb0: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
bec0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
bed0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
bee0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
bef0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
bf00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
bf10: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
bf20: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
bf30: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
bf40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
bf50: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
bf60: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
bf70: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
bf80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
bf90: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
bfa0: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
bfb0: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
bfc0: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
bfd0: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
bfe0: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
bff0: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
c000: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
c010: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
c020: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
c030: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
c040: 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63  ing mode].** doc
c050: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
c060: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
c070: 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ation.</dd>.**.*
c080: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c090: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
c0a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c0b0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c0c0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c0d0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65  .  This option e
c0e0: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
c0f0: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
c100: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
c110: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
c120: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c130: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
c140: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
c150: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
c160: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
c170: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
c180: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
c190: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
c1a0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
c1b0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c1c0: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
c1d0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
c1e0: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
c200: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c210: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
c220: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
c230: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
c240: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
c250: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c260: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
c270: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
c280: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
c290: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
c2a0: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53   same time..** S
c2b0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
c2c0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
c2d0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
c2e0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
c2f0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c300: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c310: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
c320: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
c330: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
c340: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
c350: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
c360: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
c370: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
c380: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c390: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
c3a0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
c3b0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
c3c0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
c3d0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
c3e0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
c3f0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
c400: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c410: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
c420: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a  to SQLite.</dd>.
c430: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c440: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c450: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  C</dt>.** <dd>Th
c460: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c470: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c480: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c490: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c4a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c4b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c4c0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c4d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
c4e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
c4f0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
c500: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
c510: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
c520: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
c530: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
c540: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
c550: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
c560: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
c570: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
c580: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c590: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
c5a0: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
c5b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
c5c0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
c5d0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
c5e0: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
c5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c600: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
c610: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
c620: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c630: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c640: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
c650: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
c660: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
c670: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
c680: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
c690: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
c6a0: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
c6b0: 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69  tistics. When di
c6c0: 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
c6d0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
c6e0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a  erfaces become .
c6f0: 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  ** non-operation
c700: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
c710: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c720: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
c730: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c740: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
c750: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
c760: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
c770: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
c780: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
c790: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
c7a0: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
c7b0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c7c0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
c7d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c7e0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
c7f0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
c800: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
c810: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
c820: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
c830: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
c840: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
c850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c860: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73  memory, the.** s
c870: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
c880: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c  tch buffer (sz),
c890: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
c8a0: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20  of buffers (N). 
c8b0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
c8c0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
c8d0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
c8e0: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
c8f0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
c900: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
c910: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
c920: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
c930: 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e  uired due intern
c940: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20  al overhead..** 
c950: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
c960: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
c970: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
c980: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
c990: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
c9a0: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
c9b0: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
c9c0: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
c9d0: 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65  h buffer at once
c9e0: 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a   per thread, so.
c9f0: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
ca00: 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74  et to the expect
ca10: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ca20: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54  r of threads.  T
ca30: 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74  he sz.** paramet
ca40: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74  er should be 6 t
ca50: 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66  imes the size of
ca60: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
ca70: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
ca80: 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66  .** Scratch buff
ca90: 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ers are used as 
caa0: 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65  part of the btre
cab0: 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74  e balance operat
cac0: 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20  ion.  If.** The 
cad0: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e  btree balancer n
cae0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20  eeds additional 
caf0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
cb00: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
cb10: 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66  y.** scratch buf
cb20: 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63  fers or if no sc
cb30: 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61  ratch buffer spa
cb40: 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  ce is specified,
cb50: 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
cb60: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
cb70: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62  _malloc()] to ob
cb80: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
cb90: 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a  it needs.</dd>.*
cba0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
cbb0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
cbc0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
cbd0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
cbe0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
cbf0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
cc00: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
cc10: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
cc20: 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54  e page cache.  T
cc30: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
cc40: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e  rguments: A poin
cc50: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65  ter to the.** me
cc60: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
cc70: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
cc80: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
cc90: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
cca0: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
ccb0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
ccc0: 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20   a power of two 
ccd0: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
cce0: 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73  32768.  The firs
ccf0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
cd00: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
cd10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
cd20: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
cd30: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
cd40: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
cd50: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
cd60: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
cd70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
cd80: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
cd90: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
cda0: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
cdb0: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
cdc0: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74  cache.  If addit
cdd0: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
cde0: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
cdf0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
ce00: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
ce10: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
ce20: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
ce30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
ce40: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
ce50: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
ce60: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
ce70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
ce80: 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20  ight use one or 
ce90: 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75  more of the N bu
cea0: 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a  ffers to hold .*
ceb0: 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  * memory account
cec0: 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  ing information.
ced0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
cee0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
cef0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
cf00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
cf10: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
cf20: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
cf30: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
cf40: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
cf50: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
cf60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
cf70: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
cf80: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
cf90: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
cfa0: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
cfb0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
cfc0: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
cfd0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
cfe0: 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74  guments: A point
cff0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
d000: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  , the number of.
d010: 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
d020: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
d030: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
d040: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20  llocation size. 
d050: 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   If.** the first
d060: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
d070: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
d080: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
d090: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
d0a0: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
d0b0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
d0c0: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
d0d0: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
d0e0: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
d0f0: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
d100: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
d110: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d120: 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  OC].  If the.** 
d130: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
d140: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
d150: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
d160: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
d170: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
d180: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
d190: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
d1a0: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
d1b0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d1c0: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
d1d0: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
d1e0: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
d1f0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f  ocation needs.</
d200: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d210: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
d220: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
d230: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d240: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d250: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d260: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d270: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d280: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d290: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d2a0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
d2b0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
d2c0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
d2d0: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
d2e0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
d2f0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
d300: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
d310: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
d320: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d330: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
d340: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d350: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d360: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d370: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d380: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d390: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d3a0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d3b0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d3c0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
d3d0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d3e0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
d3f0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
d400: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
d410: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
d420: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
d430: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
d440: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
d450: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
d460: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
d470: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
d480: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
d490: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
d4a0: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
d4b0: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
d4c0: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
d4d0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
d4e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d4f0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
d500: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d510: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
d520: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
d530: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
d540: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
d550: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
d560: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
d570: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d580: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
d590: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
d5a0: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
d5b0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
d5c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
d5d0: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
d5e0: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
d5f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
d600: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d620: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
d630: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
d640: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d650: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d660: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
d670: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
d680: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d690: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
d6a0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
d6b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d6c0: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
d6d0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d6e0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d6f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d700: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
d710: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
d720: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d730: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d740: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
d750: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d760: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d780: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
d790: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
d7a0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
d7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d7c0: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
d7d0: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
d7e0: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
d7f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
d800: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d810: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
d820: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
d830: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d840: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
d850: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d860: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
d870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d880: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
d890: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
d8a0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
d8b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d8c0: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
d8d0: 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20  OC   12  /* int 
d8e0: 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65  threshold */.#de
d8f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d900: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
d910: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
d920: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
d930: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
d940: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
d950: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
d960: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
d970: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
d980: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
d990: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
d9a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d9b0: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
d9c0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
d9d0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d9e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
d9f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
da00: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
da10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
da20: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
da30: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
da40: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
da50: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
da60: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
da70: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
da80: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
da90: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
daa0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
dab0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
dac0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
dad0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
dae0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
daf0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
db00: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
db10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
db20: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
db30: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
db40: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
db50: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
db60: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
db70: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
db80: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
db90: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
dba0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
dbb0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
dbc0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
dbd0: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
dbe0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
dbf0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
dc00: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
dc10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
dc20: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
dc30: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
dc40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
dc50: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
dc60: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
dc70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
dc80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
dc90: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
dca0: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
dcb0: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
dcc0: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
dcd0: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
dce0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
dcf0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
dd00: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
dd10: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
dd20: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
dd30: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
dd40: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
dd50: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
dd60: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
dd70: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
dd80: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
dd90: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
dda0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
ddb0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ddc0: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
ddd0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
dde0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ddf0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
de00: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
de10: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
de20: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
de30: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
de40: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
de50: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
de60: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
de70: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
de80: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
de90: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
dea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
deb0: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
dec0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
ded0: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
dee0: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
def0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
df00: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
df10: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
df20: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
df30: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
df40: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
df50: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
df60: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
df70: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
df80: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
df90: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
dfa0: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
dfb0: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
dfc0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
dfd0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31  S:.**.** {H12201
dfe0: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
dff0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e000: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a   shall have the.
e010: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
e020: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
e030: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61  es] feature disa
e040: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
e050: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20  .**.** {H12202} 
e060: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
e070: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
e080: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
e090: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
e0a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
e0b0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
e0c0: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61  es] for the  [da
e0d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e0e0: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
e0f0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
e100: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20  ter is true, or 
e110: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
e120: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
e130: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
e140: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
e150: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e160: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
e170: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
e180: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
e190: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
e1a0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
e1b0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
e1c0: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
e1d0: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
e1e0: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
e1f0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
e200: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
e210: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
e220: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
e230: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
e240: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
e250: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
e260: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
e270: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
e280: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
e290: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
e2a0: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
e2b0: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
e2c0: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
e2d0: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
e2e0: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
e2f0: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
e300: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
e310: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
e320: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
e330: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
e340: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
e350: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74  ul INSERT into t
e360: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
e370: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e380: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
e390: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e3a0: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63  ent.  If no succ
e3b0: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a  essful INSERTs.*
e3c0: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
e3d0: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
e3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e3f0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
e400: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
e410: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
e420: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e430: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
e440: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
e450: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
e460: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
e470: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
e480: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
e490: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
e4a0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
e4b0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
e4c0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
e4d0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
e4e0: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
e4f0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
e500: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
e510: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
e520: 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74  * An INSERT that
e530: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
e540: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
e550: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
e560: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e570: 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  RT and does not 
e580: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
e590: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
e5a0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
e5b0: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
e5c0: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
e5d0: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
e5e0: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
e5f0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
e600: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
e610: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
e620: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
e630: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
e640: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
e650: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
e660: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
e670: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
e680: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
e690: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
e6a0: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
e6b0: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
e6c0: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
e6d0: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
e6e0: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
e6f0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
e700: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
e710: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
e720: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
e730: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
e740: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
e750: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
e760: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
e770: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49  is routine, an I
e780: 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65  NSERT is conside
e790: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
e7a0: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
e7b0: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
e7c0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
e7d0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
e7e0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d  :.**.** {H12221}
e7f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
e800: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
e810: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
e820: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a  rns the rowid.**
e830: 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
e840: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
e850: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70  cessful INSERT p
e860: 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20  erformed on the 
e870: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
e880: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e890: 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69  ction] and withi
e8a0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
e8b0: 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20  gher level.**   
e8c0: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
e8d0: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
e8e0: 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65  if there have be
e8f0: 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67  en no qualifying
e900: 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20   inserts..**.** 
e910: 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {H12223} The [sq
e920: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
e930: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
e940: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
e950: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65  **          same
e960: 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c   value when call
e970: 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
e980: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e990: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d  .**          imm
e9a0: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
e9b0: 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c  and after a ROLL
e9c0: 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  BACK..**.** ASSU
e9d0: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
e9e0: 41 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70  A12232} If a sep
e9f0: 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
ea00: 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45  forms a new INSE
ea10: 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  RT on the same.*
ea20: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
ea30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
ea40: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
ea50: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
ea60: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
ea70: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
ea80: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
ea90: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
eaa0: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
eab0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
eac0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
ead0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
eae0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
eaf0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
eb00: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
eb10: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
eb20: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
eb30: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
eb40: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
eb50: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
eb60: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
eb70: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
eb80: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
eb90: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
eba0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
ebb0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
ebc0: 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20  dified {H12240} 
ebd0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
ebe0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
ebf0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
ec00: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
ec10: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
ec20: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
ec30: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
ec40: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
ec50: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
ec60: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
ec70: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
ec80: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
ec90: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
eca0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f   parameter..** O
ecb0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
ecc0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
ecd0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
ece0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
ecf0: 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  * or DELETE stat
ed00: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
ed10: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
ed20: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
ed30: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
ed40: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
ed50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
ed60: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
ed70: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
ed80: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
ed90: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
eda0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
edb0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
edc0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
edd0: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
ede0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
edf0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
ee00: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
ee10: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
ee20: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
ee30: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
ee40: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
ee50: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
ee60: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
ee70: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
ee80: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
ee90: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
eea0: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
eeb0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
eec0: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
eed0: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
eee0: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
eef0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
ef00: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
ef10: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
ef20: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
ef30: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
ef40: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
ef50: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
ef60: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
ef70: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
ef80: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
ef90: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
efa0: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
efb0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
efc0: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
efd0: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
efe0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
eff0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
f000: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
f010: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
f020: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
f030: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
f040: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
f050: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
f060: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
f070: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
f080: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
f090: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
f0a0: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
f0b0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
f0c0: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
f0d0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
f0e0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
f0f0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
f100: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
f110: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
f120: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
f130: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
f140: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
f150: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
f160: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
f170: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
f180: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
f190: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
f1a0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
f1b0: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
f1c0: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
f1d0: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
f1e0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
f1f0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
f200: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
f210: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
f220: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
f230: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
f240: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
f250: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
f260: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
f270: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
f280: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
f290: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
f2a0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
f2b0: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
f2c0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
f2d0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
f2e0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
f2f0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
f300: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
f310: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
f320: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
f330: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
f340: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
f350: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
f360: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
f370: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
f380: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
f390: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
f3a0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
f3b0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
f3c0: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
f3d0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
f3e0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
f3f0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
f400: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
f410: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
f420: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
f430: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
f440: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
f450: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
f460: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
f470: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
f480: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f490: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
f4a0: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
f4b0: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
f4c0: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
f4d0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
f4e0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f4f0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
f500: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
f510: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
f520: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
f530: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
f540: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
f550: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
f560: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
f570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f580: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
f590: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
f5a0: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
f5b0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nstead..**.** IN
f5c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f5d0: 7b 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71  {H12241} The [sq
f5e0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
f5f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
f600: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
f610: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
f620: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f630: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
f640: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
f650: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
f660: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
f670: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
f680: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
f690: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
f6a0: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
f6b0: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
f6c0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f6d0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
f6e0: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
f6f0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79      not been any
f700: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20   qualifying row 
f710: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
f720: 48 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e  H12243} Statemen
f730: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
f740: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f750: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
f760: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
f770: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61   clause shall ca
f780: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  use subsequent c
f790: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
f7a0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61      [sqlite3_cha
f7b0: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72  nges()] to retur
f7c0: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65  n zero, regardle
f7d0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ss of the.**    
f7e0: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
f7f0: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20  rows originally 
f800: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a  in the table..**
f810: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
f820: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20  .**.** {A12252} 
f830: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
f840: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
f850: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
f860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f870: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
f880: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
f890: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
f8a0: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
f8b0: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
f8c0: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65          is unpre
f8d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
f8e0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
f8f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
f900: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f920: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
f930: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
f940: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
f950: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f960: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f970: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
f980: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f990: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54  INSERT,.** UPDAT
f9a0: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
f9b0: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
f9c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f9d0: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
f9e0: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
f9f0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
fa00: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
fa10: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20  igger contexts. 
fa20: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
fa30: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
fa40: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
fa50: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
fa60: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
fa70: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
fa80: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
fa90: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44  processing, or D
faa0: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
fab0: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
fac0: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
fad0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
fae0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
faf0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20  akes them is.** 
fb00: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
fb10: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
fb20: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74  ndle is passed t
fb30: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
fb40: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
fb50: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
fb60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
fb70: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
fb80: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
fb90: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
fba0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
fbb0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
fbc0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
fbd0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
fbe0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
fbf0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
fc00: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
fc10: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
fc20: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
fc30: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
fc40: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
fc50: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
fc60: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
fc70: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
fc80: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
fc90: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
fca0: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
fcb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
fcc0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
fcd0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fce0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
fcf0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
fd00: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
fd10: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
fd20: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
fd30: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
fd40: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
fd50: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
fd60: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
fd70: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
fd80: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
fd90: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
fda0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
fdb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
fdc0: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
fdd0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
fde0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
fdf0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
fe00: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
fe10: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
fe20: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
fe30: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
fe40: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
fe50: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
fe60: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
fe70: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
fe80: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
fe90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fea0: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
feb0: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
fec0: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
fed0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
fee0: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
fef0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  eated..**.** {H1
ff00: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
ff10: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
ff20: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
ff30: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
ff40: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
ff50: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
ff60: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
ff70: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
ff80: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
ff90: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
ffa0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  )]..**.** ASSUMP
ffb0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
ffc0: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
ffd0: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
ffe0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
fff0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
10000 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
10010 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
10020 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
10030 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
10040 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
10050 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
10060 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
10070 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
10080 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
10090 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
100a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
100b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
100c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
100d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
100e0 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30   {H12270} <S3050
100f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
10100 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
10110 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
10120 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
10130 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
10140 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
10150 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
10160 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
10170 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
10180 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
10190 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
101a0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
101b0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
101c0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
101d0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
101e0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
101f0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
10200 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
10210 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
10220 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
10230 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
10240 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
10250 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
10260 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
10270 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
10280 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
10290 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
102a0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
102b0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
102c0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
102d0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
102e0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
102f0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
10300 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10310 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
10320 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70  .** If an SQL op
10330 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
10340 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
10350 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
10360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
10370 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
10380 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
10390 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
103a0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
103b0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
103c0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
103d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
103e0 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65  **.** An SQL ope
103f0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
10400 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
10410 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
10420 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
10430 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
10440 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10450 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
10460 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10470 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
10480 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
10490 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
104a0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
104b0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
104c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
104d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
104e0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
104f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
10500 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
10510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
10520 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
10530 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
10540 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
10550 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
10560 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10570 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  H12271} The [sql
10580 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10590 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
105a0 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
105b0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
105c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
105d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
105e0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
105f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
10600 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
10610 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
10620 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
10630 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61  tional row of da
10640 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37  ta..**.** {H1227
10650 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  2} Any SQL state
10660 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74  ment that is int
10670 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c  errupted by [sql
10680 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10690 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
106a0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
106b0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
106c0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
106d0 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20  .**.** {A12279} 
106e0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
106f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
10700 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
10710 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
10720 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e            is run
10730 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
10740 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
10750 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
10760 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10770 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
10780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
10790 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
107a0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
107b0 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30  Complete {H10510
107c0 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70200>.**.**
107d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
107e0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
107f0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
10800 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
10810 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
10820 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
10830 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
10840 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
10850 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
10860 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
10870 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
10880 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
10890 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
108a0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
108b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
108c0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
108d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
108e0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
108f0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
10900 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
10910 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
10920 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
10930 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
10940 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
10950 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
10960 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a  a fragment of a.
10970 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ** CREATE TRIGGE
10980 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
10990 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
109a0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
109b0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
109c0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
109d0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
109e0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
109f0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
10a00 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
10a10 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
10a20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
10a30 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
10a40 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
10a50 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
10a60 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
10a70 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ator..**.** Thes
10a80 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
10a90 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
10aa0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
10ab0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
10ac0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
10ad0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
10ae0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10af0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d  :.**.** {H10511}
10b00 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76   A successful ev
10b10 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  aluation of [sql
10b20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
10b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
10b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10b50 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73  e16()] functions
10b60 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
10b70 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65     return a nume
10b80 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c  ric 1 if and onl
10b90 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f  y if the last no
10ba0 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20  n-whitespace.** 
10bb0 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69           token i
10bc0 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
10bd0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
10be0 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77  t is not in betw
10bf0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
10c00 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
10c10 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
10c20 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
10c30 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20  .**.** {H10512} 
10c40 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
10c50 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
10c60 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e  urs during an in
10c70 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  vocation.**     
10c80 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33       of [sqlite3
10c90 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20  _complete()] or 
10ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10cb0 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a  e16()] then the.
10cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
10cd0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
10ce0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
10cf0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
10d00 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31  NS:.**.** {A1051
10d10 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
10d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10d30 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
10d40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
10d50 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
10d60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
10d70 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  A10513} The inpu
10d80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10d90 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
10da0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
10db0 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
10dc0 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
10dd0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
10de0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
10df0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
10e00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
10e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10e20 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
10e30 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
10e40 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
10e50 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
10e60 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
10e70 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
10e80 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
10e90 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10ea0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
10eb0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
10ec0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
10ed0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
10ee0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
10ef0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
10f00 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
10f10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
10f20 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
10f30 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
10f40 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
10f50 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
10f60 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10f70 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10f80 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
10f90 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
10fa0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
10fb0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
10fc0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
10fd0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
10fe0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
10ff0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
11000 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
11010 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
11020 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11030 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
11040 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
11050 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
11060 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
11070 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
11080 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
11090 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
110a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
110b0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
110c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
110d0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
110e0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
110f0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
11100 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
11110 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
11120 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
11130 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
11140 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
11150 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
11160 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
11170 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
11180 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
11190 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
111a0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
111b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
111c0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
111d0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
111e0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
111f0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
11200 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
11210 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
11220 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
11230 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
11240 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
11250 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
11260 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
11270 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
11280 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
11290 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
112a0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
112b0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
112c0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
112d0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
112e0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
112f0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
11300 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
11310 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
11320 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
11330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11340 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
11350 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
11360 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
11370 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
11380 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
11390 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
113a0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
113b0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
113c0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
113d0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
113e0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
113f0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
11400 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
11410 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
11420 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
11430 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
11440 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
11450 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
11460 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
11470 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
11480 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
11490 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
114a0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
114b0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
114c0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
114d0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
114e0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
114f0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
11500 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
11510 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
11520 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
11530 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
11540 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
11550 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
11560 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11570 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
11580 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
11590 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
115a0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
115b0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
115c0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
115d0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
115e0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
115f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
11600 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
11610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
11620 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
11630 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
11640 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11650 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
11660 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
11670 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
11680 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
11690 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
116a0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
116b0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
116c0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
116d0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
116e0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
116f0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
11700 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
11710 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
11720 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
11730 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
11740 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
11750 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
11760 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
11770 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
11780 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
11790 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
117a0 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
117b0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
117c0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
117d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
117e0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
117f0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
11800 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
11810 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
11820 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
11830 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
11840 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
11850 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
11860 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
11870 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11880 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
11890 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
118a0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
118b0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
118c0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
118d0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
118e0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
118f0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
11900 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
11910 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
11920 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
11930 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
11940 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
11950 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
11960 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
11970 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
11980 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
11990 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
119a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
119b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
119c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
119d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
119e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
119f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
11a00 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
11a10 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
11a20 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
11a30 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
11a40 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
11a50 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
11a60 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
11a70 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
11a80 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
11a90 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
11aa0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
11ab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ac0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
11ad0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11ae0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
11af0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
11b00 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
11b10 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41  ior..** .** INVA
11b20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
11b30 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  12311} The [sqli
11b40 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11b50 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f  (D,C,A)] functio
11b60 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a  n shall replace.
11b70 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79  **          busy
11b80 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
11b90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ba0 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20  ction] D with a 
11bb0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
11bc0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
11bd0 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61  er C and applica
11be0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
11bf0 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  r A..**.** {H123
11c00 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65  12} Newly create
11c10 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
11c20 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68  ections] shall h
11c30 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20  ave a busy.**   
11c40 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f         handler o
11c50 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  f NULL..**.** {H
11c60 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
11c70 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73  or more [databas
11c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
11c90 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20  hare a.**       
11ca0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
11cb0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20  le_shared_cache 
11cc0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c  | common cache],
11cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
11ce0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
11cf0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
11d10 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
11d20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
11d30 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
11d40 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
11d50 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
11d60 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36  k..**.** {H12316
11d70 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
11d80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
11d90 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
11da0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
11db0 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
11dc0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
11dd0 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
11de0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53   shall return [S
11df0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
11e00 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69  ** {H12318} SQLi
11e10 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73  te shall invokes
11e20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11e30 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
11e40 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20  ents which.**   
11e50 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70         are a cop
11e60 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
11e70 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
11e80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
11e90 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
11ea0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11eb0 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
11ec0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
11ed0 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20   of prior.**    
11ee0 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
11ef0 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61  s of the busy ha
11f00 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61  ndler for the sa
11f10 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
11f20 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11f30 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33  ONS:.**.** {A123
11f40 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c  19} A busy handl
11f50 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
11f60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
11f70 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
11f80 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72        or [prepar
11f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
11fa0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
11fb0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
11fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
11fd0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
11fe0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
11ff0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
12000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
12010 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
12020 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
12030 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
12040 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
12050 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12060 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
12070 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
12080 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
12090 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
120a0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
120b0 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
120c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
120d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
120e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
120f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
12100 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
12110 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
12120 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
12130 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
12140 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
12150 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
12160 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
12170 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
12180 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
12190 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
121a0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
121b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
121c0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
121d0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
121e0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
121f0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
12200 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
12210 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
12220 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
12230 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
12240 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
12250 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
12260 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
12270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12280 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
12290 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
122a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
122b0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
122c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
122d0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
122e0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
122f0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
12300 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
12310 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
12320 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
12330 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
12340 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
12350 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12360 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
12370 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20  ll override any 
12380 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
12390 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
123a0 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
123b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
123c0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
123e0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
123f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
12400 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20  .** {H12343} If 
12410 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
12420 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
12430 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
12440 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
12450 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
12460 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
12470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73  e busy handler s
12480 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20  hall be cleared 
12490 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  so that.**      
124a0 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65      all subseque
124b0 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  nt locking event
124c0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65  s immediately re
124d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
124e0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  Y]..**.** {H1234
124f0 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  4} If the 2nd pa
12500 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
12510 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12520 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76  ()] is a positiv
12530 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
12540 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62  mber N, then a b
12550 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
12560 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65  l be set that re
12570 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
12580 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
12590 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
125a0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  n the [sqlite3_v
125b0 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61  fs | VFS interfa
125c0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ce] until.**    
125d0 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65        either the
125e0 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
125f0 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
12600 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a  tive sleep time.
12610 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f  **          repo
12620 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c  rted back by xSl
12630 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
12640 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
12650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
12660 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
12670 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
12680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12690 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
126a0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
126b0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
126c0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
126d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
126e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
126f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
12700 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
12710 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
12720 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12730 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
12740 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
12750 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
12760 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
12770 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
12780 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
12790 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
127a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
127b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
127c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
127d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
127e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
127f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
12800 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
12810 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
12820 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
12830 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
12840 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
12850 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
12860 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
12870 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
12880 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
12890 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
128a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
128b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
128c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
128d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
128e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
128f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
12900 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
12910 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
12920 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
12930 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
12940 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
12950 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
12960 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
12970 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
12980 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
12990 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
129a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
129b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
129c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
129d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
129e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
129f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
12a00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
12a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
12a20 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
12a30 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
12a40 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
12a50 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
12a60 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
12a70 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
12a80 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
12a90 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
12aa0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
12ab0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
12ac0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
12ad0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
12ae0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
12af0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
12b00 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
12b10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12b20 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
12b30 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
12b40 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
12b50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12b60 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12b70 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
12b80 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
12b90 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
12ba0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
12bb0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
12bc0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
12bd0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
12be0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
12bf0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
12c00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12c10 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
12c20 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
12c30 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
12c40 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
12c50 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
12c60 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
12c70 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
12c80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
12c90 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
12ca0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
12cb0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
12cc0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
12cd0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
12ce0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12cf0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12d00 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
12d10 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
12d20 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
12d30 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
12d40 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
12d50 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
12d60 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
12d70 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
12d80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12d90 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
12da0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12db0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
12dc0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
12dd0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
12de0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
12df0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12e00 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
12e10 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12e20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
12e30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12e40 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
12e50 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
12e60 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
12e70 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
12e80 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
12e90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
12ea0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
12eb0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
12ec0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12ed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12ee0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12ef0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12f00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12f10 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12f20 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
12f30 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
12f40 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
12f50 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
12f60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
12f70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12f80 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
12f90 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
12fa0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
12fb0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
12fc0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12fd0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12fe0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12ff0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
13000 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
13010 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
13020 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
13030 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
13040 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
13050 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
13060 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
13070 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13080 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
13090 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
130a0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
130b0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
130c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
130d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
130e0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
130f0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
13100 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
13110 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
13120 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
13130 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
13140 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
13150 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
13160 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
13170 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
13180 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
13190 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
131a0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
131b0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
131c0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
131d0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
131e0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
131f0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
13200 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
13210 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
13220 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
13230 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
13240 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
13250 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
13260 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
13270 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13280 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31  S:.**.** {H12371
13290 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
132a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
132b0 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
132c0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
132d0 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c           it shal
132e0 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c  l free the resul
132f0 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
13300 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
13310 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
13320 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
13330 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62  ss, skip any sub
13340 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
13350 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   set the.**     
13360 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20       *pazResult 
13370 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
13380 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
13390 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
133a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d  ..**.** {H12373}
133b0 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e   If the pnColumn
133c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
133d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
133e0 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
133f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
13400 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
13410 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
13420 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13430 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
13440 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75      write the nu
13450 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
13460 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
13470 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
13480 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
13490 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  *pnColumn..**.**
134a0 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65   {H12374} If the
134b0 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72   pnRow parameter
134c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
134d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
134e0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
134f0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
13500 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
13510 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
13520 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
13530 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73            writes
13540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
13550 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
13560 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
13570 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
13580 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a  nto *pnRow..**.*
13590 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63  * {H12376} A suc
135a0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
135b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
135c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74  et_table()] that
135d0 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20   computes.**    
135e0 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20        N rows of 
135f0 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f  result with C co
13600 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68  lumns per row sh
13610 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73  all make *pazRes
13620 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
13630 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61  point to an arra
13640 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
13650 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73   (N+1)*C strings
13660 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
13670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73  .**          C s
13680 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d  trings are colum
13690 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69  n names as obtai
136a0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ned from.**     
136b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
136c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
136d0 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f   the rest are co
136e0 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75  lumn result valu
136f0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
13700 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
13710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
13720 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  t()]..**.** {H12
13730 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20  379} The values 
13740 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74  in the pazResult
13750 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20   array returned 
13760 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  by [sqlite3_get_
13770 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  table()].**     
13780 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69       shall remai
13790 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c  n valid until cl
137a0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eared by [sqlite
137b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
137c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20  .**.** {H12382} 
137d0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
137e0 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c  curs during eval
137f0 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
13800 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
13810 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
13820 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73  function shall s
13830 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f  et *pazResult to
13840 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20   NULL, write an 
13850 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
13860 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d            into m
13870 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
13880 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13890 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20  loc()], make.** 
138a0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72           **pzErr
138b0 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61  msg point to tha
138c0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c  t error message,
138d0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a   and return a.**
138e0 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
138f0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
13900 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
13910 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
13920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
13930 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
13940 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
13950 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
13960 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
13970 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
13980 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
13990 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
139a0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
139b0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
139c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
139d0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
139e0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
139f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
13a00 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
13a10 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
13a20 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
13a30 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
13a40 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
13a50 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
13a60 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
13a70 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
13a80 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
13a90 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
13aa0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
13ab0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
13ac0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37  g Functions {H17
13ad0 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32  400} <S70000><S2
13ae0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0000>.**.** Thes
13af0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
13b00 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
13b10 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
13b20 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
13b30 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
13b40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
13b50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
13b60 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
13b70 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13b80 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
13b90 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
13ba0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
13bb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
13bc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
13bd0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
13be0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
13bf0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
13c00 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
13c10 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
13c20 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20  _free()].  Both 
13c30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13c40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
13c50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
13c60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
13c70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
13c80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
13c90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
13ca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
13cb0 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
13cc0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
13cd0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
13ce0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
13cf0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
13d00 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
13d10 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
13d20 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
13d30 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
13d40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
13d50 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
13d60 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
13d70 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13d80 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
13d90 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
13da0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
13db0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
13dc0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
13dd0 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
13de0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
13df0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
13e00 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
13e10 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
13e20 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
13e30 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
13e40 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
13e50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13e60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13e70 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
13e80 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
13e90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
13ea0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
13eb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
13ec0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
13ed0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
13ee0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
13ef0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
13f00 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
13f10 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
13f20 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
13f30 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
13f40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
13f50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13f60 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
13f70 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
13f80 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
13f90 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
13fa0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
13fb0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
13fc0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13fd0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
13fe0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
13ff0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
14000 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
14010 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14020 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
14030 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
14040 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
14050 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
14060 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
14070 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
14080 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
14090 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
140a0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
140b0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
140c0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
140d0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
140e0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
140f0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
14100 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
14110 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
14120 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
14130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
14140 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
14150 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
14160 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
14170 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
14180 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
14190 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
141a0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
141b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
141c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
141d0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
141e0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
141f0 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
14200 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
14210 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
14220 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
14230 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
14240 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
14250 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
14260 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
14270 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
14280 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
14290 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
142a0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
142b0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
142c0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
142d0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
142e0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
142f0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
14300 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
14310 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
14320 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
14330 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
14340 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14350 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
14360 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
14370 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
14380 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14390 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
143a0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
143b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
143c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
143d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
143e0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
143f0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
14400 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
14410 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
14420 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
14430 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
14440 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
14450 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
14460 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
14470 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14480 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
14490 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
144a0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
144b0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
144c0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
144d0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
144e0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
144f0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
14500 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14510 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
14520 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
14530 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
14540 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
14550 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14560 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
14570 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
14580 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
14590 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
145a0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
145b0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
145c0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
145d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
145e0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
145f0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
14600 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
14610 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
14620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14630 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
14640 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
14650 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
14660 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
14670 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
14680 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
14690 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
146a0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
146b0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
146c0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
146d0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
146e0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
146f0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
14700 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
14710 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
14720 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
14730 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
14740 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
14750 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
14760 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
14770 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14780 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
14790 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
147a0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
147b0 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  le quotes) in pl
147c0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
147d0 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
147e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
147f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
14800 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14810 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
14820 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
14830 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
14840 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
14850 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
14860 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
14870 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
14880 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
14890 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
148a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
148b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
148c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
148d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
148e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
148f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
14900 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
14910 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
14920 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
14930 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
14940 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
14950 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
14960 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
14970 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
14980 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
14990 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
149a0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
149b0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
149c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
149d0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
149e0 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44  put string. {END
149f0 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  }.**.** INVARIAN
14a00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  TS:.**.** {H1740
14a10 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  3}  The [sqlite3
14a20 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20  _mprintf()] and 
14a30 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  [sqlite3_vmprint
14a40 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  f()] interfaces.
14a50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
14a60 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74  urn either point
14a70 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
14a80 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
14a90 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20  ings held in.** 
14aa0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
14ab0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
14ac0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14ad0 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ] or NULL pointe
14ae0 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  rs if.**        
14af0 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71     a call to [sq
14b00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14b10 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fails..**.** {H1
14b20 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69  7406}  The [sqli
14b30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
14b40 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73  interface writes
14b50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
14b60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
14b70 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74  UTF-8 string int
14b80 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69  o the buffer poi
14b90 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73  nted to by the s
14ba0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
14bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f  **           pro
14bc0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66  vided that the f
14bd0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
14be0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
14bf0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ero..**.** {H174
14c00 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  07}  The [sqlite
14c10 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
14c20 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
14c30 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a   write slots of.
14c40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73  **           its
14c50 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28   output buffer (
14c60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14c70 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68  eter) outside th
14c80 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20  e range.**      
14c90 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67       of 0 throug
14ca0 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69  h N-1 (where N i
14cb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
14cc0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20  meter).**       
14cd0 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f      regardless o
14ce0 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  f the length of 
14cf0 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  the string.**   
14d00 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65          requeste
14d10 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20  d by the format 
14d20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
14d30 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
14d40 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
14d50 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
14d60 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
14d70 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
14d80 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
14d90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
14da0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
14db0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
14dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
14dd0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
14de0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
14df0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
14e00 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
14e10 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
14e20 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
14e30 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
14e40 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
14e50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14e60 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
14e70 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
14e80 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
14e90 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
14ea0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
14eb0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
14ec0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
14ed0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
14ee0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
14ef0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
14f00 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
14f10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
14f20 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
14f30 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
14f40 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
14f50 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
14f60 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
14f70 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
14f80 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
14f90 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
14fa0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
14fb0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
14fc0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
14fd0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
14fe0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
14ff0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
15000 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
15010 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
15020 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
15030 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
15040 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
15050 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
15060 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
15070 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
15080 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
15090 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
150a0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
150b0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
150c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
150d0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
150e0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
150f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
15100 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
15110 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
15120 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
15130 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
15140 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
15150 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
15160 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
15170 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
15180 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
15190 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
151a0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
151b0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
151c0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
151d0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
151e0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
151f0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
15200 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
15210 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
15220 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
15230 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
15240 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
15250 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
15260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
15270 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
15280 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
15290 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
152a0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
152b0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
152c0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
152d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
152e0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
152f0 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  free()..**.** Th
15300 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
15310 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
15320 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
15330 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
15340 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
15350 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
15360 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
15370 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
15380 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
15390 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
153a0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
153b0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
153c0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
153d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
153e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
153f0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
15400 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
15410 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
15420 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
15430 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
15440 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
15450 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
15460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15470 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
15480 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
15490 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
154a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
154b0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
154c0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
154d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
154e0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
154f0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
15500 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
15510 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
15520 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
15540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
15550 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
15560 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
15570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
15580 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
15590 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
155a0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
155b0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
155c0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
155d0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
155e0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
155f0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
15600 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
15610 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
15620 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
15630 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
15640 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
15650 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
15660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15670 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
15680 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
15690 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
156a0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
156b0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
156c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
156d0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
156e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
156f0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
15700 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15710 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
15720 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
15730 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
15740 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
15750 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
15760 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
15770 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
15780 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  ion of the memor
15790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
157a0 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74  system uses.** t
157b0 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
157c0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
157d0 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
157e0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
157f0 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32  rary..** {H17382
15800 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51  } However, if SQ
15810 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15820 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
15830 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
15840 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65  <i>NNN</i> C pre
15850 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15860 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69  (where <i>NNN</i
15870 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  >.** is an integ
15880 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  er), then SQLite
15890 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
158a0 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
158b0 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  st.** <i>NNN</i>
158c0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
158d0 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72  nd uses that arr
158e0 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ay for all of it
158f0 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d  s dynamic.** mem
15900 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
15910 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
15920 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  itional memory a
15930 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73  llocator options
15940 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64  .** may be added
15950 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
15960 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
15970 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
15980 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
15990 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
159a0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
159b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
159c0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
159d0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
159e0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
159f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15a00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
15a10 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
15a20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
15a30 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
15a40 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
15a50 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15a60 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
15a70 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
15a80 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
15a90 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
15aa0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
15ab0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15ac0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
15ad0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
15ae0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
15af0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
15b00 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
15b10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
15b20 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
15b30 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
15b40 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
15b50 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
15b60 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
15b70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
15b80 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
15b90 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
15ba0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
15bb0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
15bc0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
15bd0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
15be0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
15bf0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
15c00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
15c10 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17303}  The [sql
15c20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
15c30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
15c40 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74  s either a point
15c50 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
15c60 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b     a newly check
15c70 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20  ed-out block of 
15c80 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
15c90 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   of memory.**   
15ca0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
15cb0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
15cc0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
15cd0 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
15ce0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  le.**           
15cf0 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72  to fulfill the r
15d00 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  equest..**.** {H
15d10 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c  17304}  The [sql
15d20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
15d30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
15d40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15d50 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15d60 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
15d70 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
15d80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d  ..**.** {H17305}
15d90 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66    The [sqlite3_f
15da0 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63  ree(P)] interfac
15db0 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72  e releases memor
15dc0 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  y previously.** 
15dd0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
15de0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
15df0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
15e00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15e10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
15e20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61  making it availa
15e30 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a  ble for reuse..*
15e40 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41  *.** {H17306}  A
15e50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
15e60 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73  3_free(NULL)] is
15e70 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
15e80 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30  p..**.** {H17310
15e90 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
15ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c  lite3_realloc(0,
15eb0 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e  N)] is equivalen
15ec0 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20  t to a call.**  
15ed0 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c           to [sql
15ee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e  ite3_malloc(N)].
15ef0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20  .**.** {H17312} 
15f00 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
15f10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29  te3_realloc(P,0)
15f20 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  ] is equivalent 
15f30 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  to a call.**    
15f40 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74         to [sqlit
15f50 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a  e3_free(P)]..**.
15f60 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65  ** {H17315}  The
15f70 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
15f80 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  s [sqlite3_mallo
15f90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  c()], [sqlite3_r
15fa0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
15fb0 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c          and [sql
15fc0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72  ite3_free()] for
15fd0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f   all of its memo
15fe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e  ry allocation an
15ff0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64  d.**           d
16000 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64  eallocation need
16010 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38  s..**.** {H17318
16020 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16030 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e  realloc(P,N)] in
16040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
16050 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72  either a pointer
16060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
16070 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63   a block of chec
16080 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f  ked-out memory o
16090 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
160a0 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20  es in size.**   
160b0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
160c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
160d0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
160e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31  r..**.** {H17321
160f0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
16100 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
16110 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
16120 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
16130 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
16140 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73   copies the firs
16150 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e  t K bytes of con
16160 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f  tent from P into
16170 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20   the newly.**   
16180 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
16190 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b  d block, where K
161a0 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f   is the lesser o
161b0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
161c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
161d0 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
161e0 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57  *.** {H17322}  W
161f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
16200 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
16210 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  ns a non-NULL po
16220 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a  inter, it first.
16230 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c  **           rel
16240 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72  eases the buffer
16250 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32   P..**.** {H1732
16260 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  3}  When [sqlite
16270 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
16280 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
16290 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a  e buffer P is.**
162a0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d             not m
162b0 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61  odified or relea
162c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  sed..**.** ASSUM
162d0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
162e0 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e  17350}  The poin
162f0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
16300 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16310 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
16320 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20  ealloc()].**    
16330 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65         must be e
16340 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
16350 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
16360 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
16370 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
16380 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
16390 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
163a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
163b0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
163c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
163d0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
163e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33  sed..**.** {A173
163f0 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  51}  The applica
16400 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
16410 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
16420 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  part of.**      
16430 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
16440 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
16450 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
16460 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
16470 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
16480 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
16490 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
164a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
164b0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
164c0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
164d0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
164e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
164f0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
16500 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
16510 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
16520 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c  stics {H17370} <
16530 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  S30210>.**.** SQ
16540 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
16550 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
16560 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
16570 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
16580 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
16590 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
165a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
165b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
165c0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
165d0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
165e0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
165f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
16600 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49  bsystem..**.** I
16610 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16620 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73   {H17371} The [s
16630 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16640 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
16650 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16660 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20   of bytes.**    
16670 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20        of memory 
16680 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
16690 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
166a0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
166b0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54  **.** {H17373} T
166c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
166d0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
166e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
166f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
16700 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
16710 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16720 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
16730 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16740 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  rk.**          w
16750 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
16760 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68  *.** {H17374} Th
16770 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
16780 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
16790 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
167a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
167b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
167c0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
167d0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
167e0 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
167f0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
16800 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
16810 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
16820 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
16830 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
16840 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
16850 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
16860 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
16870 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
16880 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
16890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
168a0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
168b0 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79  7375} The memory
168c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
168d0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
168e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
168f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
16900 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16910 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
16920 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
16930 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
16940 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
16950 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16960 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
16970 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
16980 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
16990 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
169a0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
169b0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
169c0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f  **          prio
169d0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
169e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
169f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
16a00 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
16a10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
16a20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
16a30 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
16a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16a50 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
16a60 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
16a70 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30  or {H17390} <S20
16a80 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  000>.**.** SQLit
16a90 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
16aa0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
16ab0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
16ac0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
16ad0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
16ae0 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
16af0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
16b00 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
16b10 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
16b20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
16b30 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
16b40 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
16b50 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
16b60 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
16b70 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
16b80 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
16b90 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
16ba0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
16bb0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
16bc0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
16bd0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
16be0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
16bf0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
16c00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
16c10 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
16c20 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
16c30 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
16c40 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
16c50 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
16c60 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
16c70 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
16c80 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
16c90 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
16ca0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
16cb0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
16cc0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
16cd0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
16ce0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
16cf0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
16d00 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
16d10 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
16d20 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
16d30 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
16d40 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
16d50 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
16d60 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
16d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
16d80 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
16d90 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
16da0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
16db0 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {H17392} The [sq
16dc0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
16dd0 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
16de0 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
16df0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
16e00 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
16e10 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
16e20 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
16e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
16e40 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
16e50 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
16e60 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
16e70 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
16e80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
16e90 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e  H12500} <S70100>
16ea0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
16eb0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
16ec0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16ed0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
16ee0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
16ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
16f00 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
16f10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
16f20 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
16f30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
16f40 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
16f50 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
16f60 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
16f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16f80 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
16f90 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
16fa0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
16fb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16fc0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
16fd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
16fe0 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
16ff0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
17000 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
17010 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
17020 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
17030 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
17040 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
17050 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
17060 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
17070 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
17080 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
17090 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
170a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
170b0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
170c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
170d0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
170e0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
170f0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
17100 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
17110 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
17120 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
17130 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
17140 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
17150 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
17160 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
17170 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
17180 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
17190 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
171a0 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74   an error.  If t
171b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
171c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
171d0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
171e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
171f0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
17200 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
17210 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
17220 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
17230 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
17240 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
17250 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
17260 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
17270 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
17280 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
17290 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
172a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
172b0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
172c0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
172d0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
172e0 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
172f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17300 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
17310 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
17320 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17330 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
17340 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
17350 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
17360 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
17370 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
17380 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
17390 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
173a0 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65   denied.  If the
173b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
173c0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
173d0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
173e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
173f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
17400 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
17410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
17420 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
17430 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
17440 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
17450 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
17460 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
17470 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
17480 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
17490 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
174a0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
174b0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
174c0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
174d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
174e0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
174f0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
17500 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
17510 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
17520 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
17530 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17550 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17560 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
17570 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
17580 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
17590 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
175a0 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e  rface. The secon
175b0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
175c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
175d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
175e0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
175f0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
17600 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
17610 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
17620 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17630 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72  d. The third thr
17640 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
17650 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
17660 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
17670 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17680 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
17690 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
176a0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
176b0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
176c0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
176d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
176e0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
176f0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
17700 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
17710 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
17720 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
17730 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
17740 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
17750 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
17760 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
17770 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
17780 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
17790 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
177a0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
177b0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
177c0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
177d0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
177e0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
177f0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
17800 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
17810 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
17820 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
17830 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
17840 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
17850 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
17860 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
17870 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
17880 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
17890 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
178a0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
178b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
178c0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
178d0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
178e0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
178f0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
17900 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
17910 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17920 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
17930 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
17940 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
17950 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
17960 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
17970 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
17980 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
17990 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
179a0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
179b0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
179c0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
179d0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
179e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
179f0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
17a00 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
17a10 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
17a20 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
17a30 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
17a40 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
17a50 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
17a60 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
17a70 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
17a80 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
17a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17aa0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
17ab0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
17ac0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ad0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
17ae0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
17af0 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
17b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
17b10 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
17b20 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
17b30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
17b40 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
17b50 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
17b60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17b70 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
17b80 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
17b90 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
17ba0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17bb0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
17bc0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
17bd0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
17be0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
17bf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17c00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
17c10 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
17c20 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
17c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
17c40 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
17c50 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
17c60 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
17c70 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  .** When [sqlite
17c80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17c90 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
17ca0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
17cb0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
17cc0 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70   might be reprep
17cd0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
17ce0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
17cf0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
17d00 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
17d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17d20 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
17d30 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
17d40 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
17d50 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
17d60 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
17d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
17d80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ()]..**.** Note 
17d90 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
17da0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17db0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
17dc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
17dd0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
17de0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
17df0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
17e00 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
17e10 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
17e20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
17e30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
17e40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
17e50 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d  :.**.** {H12501}
17e60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17e70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e  t_authorizer(D,.
17e80 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
17e90 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20  egisters a.**   
17ea0 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
17eb0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
17ec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ed0 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ion D..**.** {H1
17ee0 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72  2502} The author
17ef0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17f00 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
17f10 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
17f20 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67  *          being
17f30 20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d   parseed and com
17f40 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  piled..**.** {H1
17f50 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74  2503} If the aut
17f60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17f70 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c   returns any val
17f80 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
17f90 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
17fa0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
17fb0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
17fc0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a  TE_DENY], then.*
17fd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
17fe0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72  pplication inter
17ff0 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63  face call that c
18000 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
18010 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
18020 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
18030 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
18040 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
18050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
18060 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
18070 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
18080 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
18090 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20  * {H12504} When 
180a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
180b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
180c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
180d0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
180e0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
180f0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
18100 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rmally..**.** {H
18110 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
18120 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18130 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
18140 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
18150 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69  *          appli
18160 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65  cation interface
18170 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
18180 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  d the.**        
18190 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
181a0 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
181b0 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20  ll fail.**      
181c0 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c      with an [SQL
181d0 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
181e0 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72   code and an err
181f0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
18200 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e         explainin
18210 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73  g that access is
18220 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   denied..**.** {
18230 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61  H12506} If the a
18240 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
18250 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
18260 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
18270 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
18280 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51  callback) is [SQ
18290 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74  LITE_READ] and t
182a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
182b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
182c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
182d0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e  TE_IGNORE], then
182e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
182f0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
18300 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20  ructed to.**    
18310 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e        insert a N
18320 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
18330 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
18340 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
18350 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  d have.**       
18360 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20     been read if 
18370 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
18380 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a  been returned..*
18390 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66  *.** {H12507} If
183a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
183b0 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
183c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
183d0 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
183e0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
183f0 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  is anything othe
18400 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
18410 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  EAD], then.**   
18420 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
18430 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  of [SQLITE_IGNOR
18440 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  E] has the same 
18450 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54  effect as [SQLIT
18460 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DENY]..**.** {
18470 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73  H12510} The firs
18480 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
18490 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
184a0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
184b0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
184c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
184d0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
184e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
184f0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  er()] interface.
18500 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20  .**.** {H12511} 
18510 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18520 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
18530 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18540 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
18550 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
18560 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
18570 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
18580 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
18590 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62  **          to b
185a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
185b0 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65  .** {H12512} The
185c0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
185d0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
185e0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
185f0 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
18600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18610 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
18620 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tain.**         
18630 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
18640 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
18650 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
18660 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rized..**.** {H1
18670 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20  2520} Each call 
18680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  to [sqlite3_set_
18690 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76  authorizer()] ov
186a0 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20  errides.**      
186b0 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73      any previous
186c0 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74  ly installed aut
186d0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  horizer..**.** {
186e0 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61  H12521} A NULL a
186f0 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
18700 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
18710 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
18720 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e    callback is in
18730 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
18740 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
18750 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
18760 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
18770 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18780 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
18790 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
187a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
187b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
187c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
187d0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
187e0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
187f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18800 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
18810 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39  urn Codes {H1259
18820 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a  0} <H12500>.**.*
18830 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
18840 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
18870 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
18880 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
18890 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
188a0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
188b0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
188c0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
188d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
188e0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
188f0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
18900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18910 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18920 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
18930 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
18940 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
18950 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
18960 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
18970 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
18980 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
18990 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
189a0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
189b0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
189c0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
189d0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
189e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
189f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
18a00 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
18a10 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31  des {H12550} <H1
18a20 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
18a30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18a40 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
18a50 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
18a60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18a70 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
18a80 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
18a90 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
18aa0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
18ab0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18ac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18ad0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
18ae0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
18af0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
18b00 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
18b10 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18b20 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18b30 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18b40 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18b50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b60 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18b80 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18b90 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
18ba0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
18bb0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
18bc0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
18bd0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
18be0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
18bf0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
18c00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18c10 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
18c20 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18c30 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18c40 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18c50 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18c60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18c70 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
18c80 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
18c90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18ca0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
18cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
18cc0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
18cd0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
18ce0 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20  cable.  The 6th 
18cf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18d00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18d10 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
18d20 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
18d30 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
18d40 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18d50 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18d60 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18d70 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18d80 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18d90 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18da0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
18db0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a   SQL code..**.**
18dc0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
18dd0 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20  ** {H12551} The 
18de0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18df0 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20   to an.**       
18e00 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
18e10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
18e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18e30 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e  ] shall be an in
18e40 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
18e50 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18e60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
18e70 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
18e80 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
18e90 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
18ea0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
18eb0 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65  .** {H12552} The
18ec0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
18ed0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ameters to the.*
18ee0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18ef0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18f00 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
18f10 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20  on callback].** 
18f20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62           shall b
18f30 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
18f40 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
18f50 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  n which.**      
18f60 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
18f70 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
18f80 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74  de] is used as t
18f90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18fa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ter..**.** {H125
18fb0 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61  53} The 5th para
18fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18fd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18fe0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18ff0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
19000 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65  llback] shall be
19010 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
19020 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74        of the dat
19030 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20  abase (example: 
19040 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
19050 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
19060 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ble..**.** {H125
19070 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61  54} The 6th para
19080 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
19090 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
190a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
190b0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
190c0 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65  llback] shall be
190d0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
190e0 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e        of the inn
190f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
19100 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
19110 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
19120 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19130 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
19140 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
19150 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
19160 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
19170 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c  *          top-l
19180 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
19190 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
191a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
191b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
191c0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
191d0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
191e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
191f0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
19200 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
19210 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19240 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
19250 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
19260 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19290 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
192a0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
192b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
192c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
192d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
192e0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
192f0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
19300 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19320 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19330 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
19340 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
19350 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
19360 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19370 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19380 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
19390 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
193a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
193b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
193c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
193d0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
193e0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
193f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19400 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19410 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19420 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
19430 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19460 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
19470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
19480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19490 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
194a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
194b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
194c0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
194d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
194e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
194f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19500 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
19510 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
19520 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19550 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
19560 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
19570 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19580 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
195a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
195b0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
195c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
195d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
195e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
195f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
19600 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
19610 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
19620 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19640 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
19650 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
19660 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
19670 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19690 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
196a0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
196b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
196c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
196d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
196e0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
196f0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
19700 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
19730 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
19740 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
19750 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19760 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
19780 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
19790 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
197a0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
197b0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
197c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
197d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
197e0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
197f0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19800 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19810 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
19820 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
19830 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
19840 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
19850 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19860 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
19870 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
19880 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  22   /* NULL    
19890 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
198a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
198b0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
198c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
198d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
198e0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
198f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19900 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
19910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
19920 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
19930 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19940 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19950 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
19960 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
19970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
19980 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
19990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
199a0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
199b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
199c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
199d0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
199e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
199f0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
19a00 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
19a10 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19a20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19a30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19a40 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
19a50 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
19a60 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19a70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19a80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19a90 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
19aa0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
19ab0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19ac0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19ad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19ae0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
19af0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
19b00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19b10 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
19b20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b30 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
19b40 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46         31   /* F
19b50 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e  unction Name   N
19b60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b80 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
19b90 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
19ba0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
19bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19bc0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
19bd0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
19be0 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
19bf0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
19c00 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  AL.**.** These r
19c10 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
19c20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19c30 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
19c40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
19c50 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
19c60 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
19c70 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19c80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
19c90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19ca0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19cb0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
19cc0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
19cd0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
19ce0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
19cf0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
19d00 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
19d10 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
19d20 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
19d30 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
19d40 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19d50 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
19d60 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
19d70 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
19d80 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
19d90 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
19da0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
19db0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
19dc0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
19dd0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
19de0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
19df0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
19e00 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
19e10 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
19e20 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
19e30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19e40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19e50 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
19e60 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
19e70 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19e80 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
19e90 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ea0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
19eb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
19ec0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
19ed0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
19ee0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
19ef0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
19f00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
19f10 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
19f20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
19f30 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63  * {H12281} The c
19f40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19f50 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
19f60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
19f70 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68   .**          sh
19f80 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  all be invoked.*
19f90 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
19fa0 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ver an SQL state
19fb0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
19fc0 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64  s to execute and
19fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
19fe0 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20  never a trigger 
19ff0 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74  subprogram first
1a000 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a   begins to run..
1a010 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45  **.** {H12282} E
1a020 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
1a030 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68  ite3_trace()] sh
1a040 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65  all override the
1a050 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
1a060 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
1a070 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ed trace callbac
1a080 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33  k..**.** {H12283
1a090 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63  } A NULL trace c
1a0a0 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69  allback shall di
1a0b0 73 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a  sable tracing..*
1a0c0 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68  *.** {H12284} Th
1a0d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a0e0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
1a0f0 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20  llback shall be 
1a100 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
1a110 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65        the pointe
1a120 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
1a130 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
1a140 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1a150 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35  ]..**.** {H12285
1a160 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  } The second arg
1a170 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
1a180 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ce callback is a
1a190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a1a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a1b0 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
1a1c0 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ning the origina
1a1d0 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  l text.**       
1a1e0 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74     of the SQL st
1a1f0 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
1a200 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73  s passed into [s
1a210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a220 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
1a230 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
1a240 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  nt, or an SQL co
1a250 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67  mment indicating
1a260 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a   the beginning.*
1a270 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20  *          of a 
1a280 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
1a290 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  am..**.** {H1228
1a2a0 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  7} The callback 
1a2b0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1a2c0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
1a2d0 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e  profile()] is in
1a2e0 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
1a2f0 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74    as each SQL st
1a300 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1a310 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d  ..**.** {H12288}
1a320 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1a330 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1a340 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1a350 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
1a360 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61        the 3rd pa
1a370 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1a380 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a  te3_profile()]..
1a390 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54  **.** {H12289} T
1a3a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a3b0 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1a3c0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1a3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a3e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a3f0 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  -8 string that c
1a400 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70  ontains the comp
1a410 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20  lete text of.** 
1a420 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c           the SQL
1a430 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
1a440 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62   was processed b
1a450 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1a460 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
1a470 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
1a480 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  valent..**.** {H
1a490 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64  12290} The third
1a4a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a4b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1a4c0 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ck is an estimat
1a4d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1a4e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
1a4f0 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61  anoseconds of wa
1a500 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65  ll-clock time re
1a510 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20  quired to.**    
1a520 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51        run the SQ
1a530 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d  L statement from
1a540 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68   start to finish
1a550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
1a560 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1a570 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1a580 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1a590 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1a5a0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1a5b0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1a5c0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1a5d0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1a5e0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1a5f0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1a600 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1a610 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1a620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a630 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1a640 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
1a650 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
1a660 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1a670 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
1a680 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a690 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
1a6a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
1a6b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
1a6c0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1a6d0 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
1a6e0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
1a6f0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1a700 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1a710 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
1a720 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
1a730 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1a740 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1a750 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1a760 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1a770 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1a780 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
1a790 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1a7a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1a7b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1a7c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1a7d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1a7e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a7f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1a800 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1a810 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1a820 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1a830 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1a840 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a850 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1a860 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1a870 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a880 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1a890 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1a8a0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1a8b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1a8c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a8d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1a8e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1a8f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1a900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1a910 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1a920 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1a930 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1a940 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1a950 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54  **.** {H12911} T
1a960 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1a970 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1a980 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  by sqlite3_progr
1a990 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1a9a0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
1a9b0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1a9c0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1a9d0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1a9e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a9f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1aa00 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20  ** {H12912} The 
1aa10 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1aa20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
1aa30 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
1aa40 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
1aa50 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
1aa60 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1aa70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1aa80 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1aa90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1aaa0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1aab0 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69  ] call that regi
1aac0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
1aad0 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e     the callback.
1aae0 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74    If N is less t
1aaf0 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70  han 1, sqlite3_p
1ab00 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1ab10 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63  ).**          ac
1ab20 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20  ts as if a NULL 
1ab30 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ab40 20 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66   had been specif
1ab50 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ied..**.** {H129
1ab60 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  13} The progress
1ab70 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66   callback itself
1ab80 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
1ab90 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20  y the third.**  
1aba0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
1abb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   to sqlite3_prog
1abc0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a  ress_handler()..
1abd0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54  **.** {H12914} T
1abe0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1abf0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
1ac00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1ac10 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
1ac20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
1ac30 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
1ac40 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
1ac50 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
1ac60 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
1ac70 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1ac80 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61  ** {H12915} If a
1ac90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1aca0 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
1acb0 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20  s in fewer than 
1acc0 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20  N opcodes.**    
1acd0 20 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63        being exec
1ace0 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
1acf0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ad00 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65   is never invoke
1ad10 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36  d..**.** {H12916
1ad20 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20  } Every call to 
1ad30 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
1ad40 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20  s_handler()].** 
1ad50 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69           overwri
1ad60 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73  tes any previous
1ad70 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72  ly registered pr
1ad80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1ad90 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49  **.** {H12917} I
1ada0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  f the progress h
1adb0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1adc0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20  is NULL then no 
1add0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20  progress.**     
1ade0 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20       handler is 
1adf0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1ae00 48 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70  H12918} If the p
1ae10 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ae20 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1ae30 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20  t other than 0, 
1ae40 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
1ae50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1ae60 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69   a if [sqlite3_i
1ae70 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20  nterrupt()] had 
1ae80 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20  been called..** 
1ae90 20 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30           <S30500
1aea0 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  >.*/.void sqlite
1aeb0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1aec0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1aed0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1aee0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1aef0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1af00 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1af10 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32   Connection {H12
1af20 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a  700} <S40200>.**
1af30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1af40 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1af50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1af60 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
1af70 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
1af80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1af90 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
1afa0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1afb0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1afc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1afd0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1afe0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1aff0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1b000 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1b010 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1b020 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61  _open16(). A [da
1b030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b040 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1b050 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1b060 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1b070 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1b080 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1b090 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1b0a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1b0b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1b0c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1b0d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1b0e0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1b0f0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1b100 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1b110 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1b120 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1b130 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66  3].** object. If
1b140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1b150 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1b160 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1b170 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1b180 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1b190 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1b1a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1b1b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  e] is returned. 
1b1c0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
1b1d0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1b1e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b1f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1b200 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1b210 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1b220 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1b230 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1b240 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  r..**.** The def
1b250 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1b260 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1b270 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1b280 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1b290 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1b2a0 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1b2b0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1b2c0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1b2d0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1b2e0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1b2f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1b300 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1b310 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1b320 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1b330 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1b340 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1b350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b360 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1b370 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1b380 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1b390 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1b3a0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1b3b0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1b3c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1b3d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1b3e0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1b3f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1b400 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1b410 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1b420 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1b430 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1b440 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1b450 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1b460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b470 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
1b480 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65  rameter can take
1b490 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
1b4a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
1b4b0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
1b4c0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1b4d0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b4e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
1b4f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1b500 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a  LLMUTEX] flags:.
1b510 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
1b520 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1b530 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1b540 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1b550 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1b560 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1b570 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b580 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1b590 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1b5a0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1b5b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1b5c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1b5d0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1b5e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1b5f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1b600 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1b610 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1b620 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1b630 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1b640 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1b650 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1b660 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1b670 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1b680 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1b690 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1b6a0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1b6b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1b6c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
1b6d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1b6e0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1b6f0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1b700 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1b710 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1b720 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b730 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1b740 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
1b750 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1b760 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1b770 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1b780 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1b790 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1b7a0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b7b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b7c0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1b7d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1b7e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b7f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1b800 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1b810 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1b820 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1b830 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1b840 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1b850 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1b860 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1b870 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f  _OPEN_NOMUTEX] o
1b880 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  r [SQLITE_OPEN_F
1b890 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c  ULLMUTEX] flags,
1b8a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1b8b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1b8c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
1b8d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b8e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1b8f0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1b900 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b910 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1b920 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1b930 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1b940 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1b950 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1b960 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1b970 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1b980 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1b990 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
1b9a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1b9b0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1b9c0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1b9d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b9e0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1b9f0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1ba00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1ba10 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1ba20 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1ba30 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1ba40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1ba50 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  tart-time..**.**
1ba60 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1ba70 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1ba80 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1ba90 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1baa0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1bab0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1bac0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1bad0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1bae0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1baf0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1bb00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bb10 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1bb20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1bb30 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1bb40 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1bb50 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1bb60 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1bb70 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1bb80 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1bb90 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1bba0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1bbb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1bbc0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1bbd0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1bbe0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1bbf0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1bc00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1bc10 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1bc20 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1bc30 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1bc40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1bc50 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1bc60 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1bc70 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1bc80 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1bc90 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1bca0 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
1bcb0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1bcc0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1bcd0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1bce0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1bcf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bd00 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1bd10 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
1bd20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1bd30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bd40 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1bd50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1bd60 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1bd70 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1bd80 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1bd90 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1bda0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1bdb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1bdc0 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66  d use.  If the f
1bdd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bde0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1bdf0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1be00 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1be10 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1be20 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1be30 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1be40 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1be50 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1be60 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1be70 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1be80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1be90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bea0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1beb0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1bec0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1bed0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1bee0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1bef0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1bf00 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1bf10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1bf20 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1bf30 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1bf40 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1bf50 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1bf60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1bf70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1bf80 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54  **.** {H12701} T
1bf90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1bfa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1bfb0 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1bfc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1bfd0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1bfe0 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61  erfaces create a
1bff0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
1c000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c010 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
1c020 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
1c030 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1c040 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
1c050 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
1c060 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1c070 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  02} The filename
1c080 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1c090 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1c0a0 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  8.**          fo
1c0b0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
1c0c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c0d0 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
1c0e0 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  s UTF-16.**     
1c0f0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
1c100 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
1c110 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1c120 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
1c130 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  703} A successfu
1c140 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
1c150 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1c160 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1c170 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1c180 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1c190 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20  en_v2()] writes 
1c1a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1c1b0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1c1c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c1d0 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e  ion] into *ppDb.
1c1e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20  .**.** {H12704} 
1c1f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1c200 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1c210 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1c220 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c230 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1c240 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1c250 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e  [SQLITE_OK] upon
1c260 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20   success,.**    
1c270 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72        or an appr
1c280 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
1c290 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
1c2a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20  .**.** {H12706} 
1c2b0 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1c2c0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1c2d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1c2e0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1c2f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c300 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
1c310 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1c320 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a  ill be UTF-8..**
1c330 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65  .** {H12707} The
1c340 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1c350 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1c360 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1c370 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1c380 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1c390 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  n16()] will be U
1c3a0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  TF-16..**.** {H1
1c3b0 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2709} The [sqlit
1c3c0 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e  e3_open(F,D)] in
1c3d0 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
1c3e0 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  alent to.**     
1c3f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1c400 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20  en_v2(F,D,G,0)] 
1c410 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61  where the G para
1c420 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1c430 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45       [SQLITE_OPE
1c440 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51  N_READWRITE]|[SQ
1c450 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c460 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31  ]..**.** {H12711
1c470 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1c480 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c490 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1c4a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1c4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1c4c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1c4d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65  EN_READONLY] the
1c4e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1c4f0 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
1c500 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67       for reading
1c510 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   only..**.** {H1
1c520 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70  2712} If the G p
1c530 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c540 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c550 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1c560 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c570 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1c580 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c590 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1c5a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1c5b0 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e            readin
1c5c0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1c5d0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f   possible, or fo
1c5e0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
1c5f0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1c600 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20    file is write 
1c610 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1c620 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1c630 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33  m..**.** {H12713
1c640 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1c650 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c660 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1c670 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20  )] omits the.** 
1c680 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1c690 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1c6a0 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1c6b0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1c6c0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1c6d0 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1c6e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1c6f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rned..**.** {H12
1c700 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61  714} If the G pa
1c710 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1c720 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1c730 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1c740 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1c750 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1c760 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1c770 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1c780 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1c790 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1c7a0 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74  xist, then an at
1c7b0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1c7c0 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20   create and.**  
1c7d0 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69          initiali
1c7e0 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ze the database.
1c7f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20  .**.** {H12717} 
1c800 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1c810 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1c820 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1c830 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1c840 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1c850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c860 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79  2()] is ":memory
1c870 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
1c880 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1c890 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d   ephemeral, in-m
1c8a0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
1c8b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1c8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
1c8d0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1c8e0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1c8f0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1c900 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1c910 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1c920 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1c930 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1c940 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20  .** {H12719} If 
1c950 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1c960 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
1c970 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
1c980 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1c990 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f       ephemeral o
1c9a0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1c9b0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1c9c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1c9d0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1c9e0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1c9f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1ca00 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1ca10 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1ca20 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1ca30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20  .**.** {H12721} 
1ca40 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
1ca50 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
1ca60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d by [sqlite3_op
1ca70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a  en_v2(F,D,G,V)].
1ca80 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
1ca90 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1caa0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
1cab0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1cac0 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20  V parameter,.** 
1cad0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1cae0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1caf0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20  _vfs] object if 
1cb00 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
1cb10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1cb20 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73  23} Two [databas
1cb30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
1cb40 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d  ill share a comm
1cb50 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68  on cache if both
1cb60 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   were.**        
1cb70 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68    opened with th
1cb80 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65  e same VFS while
1cb90 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1cba0 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64  ode] was enabled
1cbb0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1cbc0 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d   if both filenam
1cbd0 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  es compare equal
1cbe0 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20   using memcmp() 
1cbf0 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65  after having bee
1cc00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  n.**          pr
1cc10 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b  ocessed by the [
1cc20 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46  sqlite3_vfs | xF
1cc30 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74  ullPathname] met
1cc40 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a  hod of the VFS..
1cc50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1cc60 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1cc70 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1cc80 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1cc90 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1cca0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1ccb0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1ccc0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1ccd0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1cce0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1ccf0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1cd00 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1cd10 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cd20 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1cd30 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1cd40 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1cd50 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1cd60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cd70 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1cd80 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1cd90 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1cda0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1cdb0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1cdc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1cdd0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1cde0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1cdf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ce00 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1ce10 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1ce20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1ce30 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1ce40 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1ce50 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1ce60 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1ce70 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32  s {H12800} <S602
1ce80 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
1ce90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1cea0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1ceb0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1cec0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1ced0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1cee0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1cef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1cf00 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1cf10 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1cf20 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1cf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf40 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1cf50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1cf60 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1cf70 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1cf80 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1cf90 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1cfa0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1cfb0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1cfc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1cfd0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1cfe0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1cff0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1d000 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1d010 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1d020 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1d030 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1d040 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1d050 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1d060 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1d070 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1d080 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1d090 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1d0a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1d0b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1d0c0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1d0d0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1d0e0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1d0f0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1d100 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1d110 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1d120 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1d130 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1d140 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1d150 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
1d160 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1d170 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1d180 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1d190 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1d1a0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1d1b0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1d1c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1d1d0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1d1e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1d1f0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1d200 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1d210 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
1d220 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1d230 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1d240 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1d250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1d260 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1d270 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74           [result
1d280 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
1d290 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1d2a0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1d2b0 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  cently.**       
1d2c0 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66     failed interf
1d2d0 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
1d2e0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1d2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d300 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
1d310 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
1d320 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
1d330 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d340 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  16(D)].**       
1d350 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1d360 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1d370 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20  guage text that 
1d380 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20  describes.**    
1d390 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20        the error 
1d3a0 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65  in the mostly re
1d3b0 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
1d3c0 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a  terface call,.**
1d3d0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65            encode
1d3e0 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  d as either UTF-
1d3f0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1d400 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
1d410 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {H12807} The str
1d420 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1d430 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d440 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1d450 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
1d460 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1d470 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
1d480 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
1d490 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
1d4a0 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  H12808} Calls to
1d4b0 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
1d4c0 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
1d4d0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
1d4e0 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
1d4f0 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
1d500 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
1d510 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1d520 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
1d530 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
1d540 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1d550 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1d560 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1d570 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d580 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1d590 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1d5a0 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1d5b0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1d5c0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1d5d0 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1d5e0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1d5f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1d600 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1d610 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1d620 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1d630 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1d640 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1d650 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1d660 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1d670 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1d680 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d690 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1d6a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d6b0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1d6c0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
1d6d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1d6e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1d6f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1d700 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1d710 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1d720 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1d730 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1d740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d750 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1d760 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
1d770 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
1d780 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1d790 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1d7a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1d7b0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1d7c0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1d7d0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1d7e0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1d7f0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1d800 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1d810 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1d820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1d830 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1d840 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1d850 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1d860 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1d870 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1d880 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1d890 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1d8a0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1d8b0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1d8c0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1d8d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1d8e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1d8f0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1d900 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1d910 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1d920 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1d930 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1d940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1d950 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1d960 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1d970 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1d980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1d990 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1d9a0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1d9b0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1d9c0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1d9d0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1d9e0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1d9f0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1da00 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1da10 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1da20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1da30 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1da40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1da50 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1da60 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1da70 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1da80 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1da90 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1daa0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1dab0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1dac0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1dad0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1dae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1daf0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
1db00 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
1db10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1db20 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1db30 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1db40 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1db50 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1db60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1db70 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1db80 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1db90 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1dba0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dbb0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1dbc0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1dbd0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1dbe0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1dbf0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1dc00 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1dc10 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1dc20 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1dc30 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1dc40 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1dc50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1dc60 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1dc70 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1dc80 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1dc90 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1dca0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
1dcb0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
1dcc0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1dcd0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1dce0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1dcf0 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
1dd00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1dd10 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1dd20 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61  YZ there is a ha
1dd30 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e  rd upper.** boun
1dd40 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  d set by a compi
1dd50 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1dd60 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1dd70 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59  ed SQLITE_MAX_XY
1dd80 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  Z..** (The "_LIM
1dd90 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1dda0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1ddb0 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65  _MAX_".).** Atte
1ddc0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1ddd0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1dde0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1ddf0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1de00 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1de10 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1de20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  limit..**.** Run
1de30 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65   time limits are
1de40 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1de50 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1de60 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1de70 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1de80 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1de90 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1dea0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1deb0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1dec0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1ded0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1dee0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1def0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1df00 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74   webbrowser that
1df10 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1df20 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1df30 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1df40 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1df50 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1df60 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1df70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1df80 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1df90 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1dfa0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1dfb0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1dfc0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1dfd0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1dfe0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1dff0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1e000 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1e010 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1e020 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1e030 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1e040 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1e050 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1e060 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1e070 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1e080 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1e090 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1e0a0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1e0b0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1e0c0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1e0d0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1e0e0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1e0f0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1e100 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1e110 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1e120 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1e130 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1e140 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1e150 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1e160 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1e170 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1e180 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eases..**.** INV
1e190 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1e1a0 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73  H12762} A succes
1e1b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1e1c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1e1d0 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a  V)] where V is.*
1e1e0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74  *          posit
1e1f0 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ive changes the 
1e200 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1e210 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1e220 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1e230 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1e240 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74  nnection] D to t
1e250 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61  he lesser of V a
1e260 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65  nd the hard uppe
1e270 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f  r.**          bo
1e280 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  und on the size 
1e290 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74  of C that is set
1e2a0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1e2b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d  ..**.** {H12766}
1e2c0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1e2d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1e2e0 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1e2f0 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65  re V is negative
1e300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61  .**          lea
1e310 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66  ves the state of
1e320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1e330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63  onnection] D unc
1e340 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
1e350 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73  12769} A success
1e360 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1e370 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1e380 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  )] returns the.*
1e390 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
1e3a0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e   of the limit on
1e3b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1e3c0 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1e3d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1e3e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e3f0 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
1e400 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
1e410 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e420 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1e430 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1e440 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1e450 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1e460 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
1e470 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
1e480 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1e490 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1e4a0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
1e4b0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
1e4c0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
1e4d0 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20  various aspects 
1e4e0 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  of a [database c
1e4f0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
1e500 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65  at can be limite
1e510 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c  d in size by cal
1e520 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ls to [sqlite3_l
1e530 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1e540 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1e550 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61  various limits a
1e560 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  re as follows:.*
1e570 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1e580 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1e590 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1e5a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1e5b0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1e5c0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1e5d0 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
1e5e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e5f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1e600 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e610 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1e620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1e630 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e640 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1e650 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1e660 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e670 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e680 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1e690 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1e6a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1e6b0 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61  SELECT or the ma
1e6c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1e6d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1e6e0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1e6f0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1e700 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1e710 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1e720 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1e730 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1e740 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1e750 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1e760 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1e770 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
1e780 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e790 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1e7a0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1e7b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e7c0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1e7d0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1e7e0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1e7f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e800 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1e810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e820 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e830 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1e840 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1e850 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1e860 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1e870 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1e880 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e890 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
1e8a0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
1e8b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e8c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
1e8d0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
1e8e0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
1e8f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e900 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1e910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e920 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74  um number of att
1e930 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e  ached databases.
1e940 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1e960 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1e970 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e980 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1e990 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1e9a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c  rgument to the L
1e9b0 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f  IKE or.** GLOB o
1e9c0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a  perators.</dd>.*
1e9d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e9e0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1e9f0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
1ea00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1ea10 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
1ea20 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
1ea30 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
1ea40 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
1ea50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1ea60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1ea70 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1ea90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1eaa0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1eab0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1eac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ead0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1eaf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1eb00 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1eb10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1eb20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eb30 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1eb40 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1eb50 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1eb60 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1eb70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb80 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1eb90 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1eba0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1ebb0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1ebc0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1ebd0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1ebe0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1ebf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1ec00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1ec10 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1ec20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ec30 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1ec40 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41       9../*.** CA
1ec50 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1ec60 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1ec70 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30  nt {H13010} <S10
1ec80 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000>.** KEYWORDS
1ec90 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
1eca0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
1ecb0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1ecc0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1ecd0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1ece0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1ecf0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1ed00 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1ed10 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
1ed20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1ed30 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
1ed40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1ed50 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
1ed60 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
1ed70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1ed80 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1ed90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1eda0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1edb0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6()]..**.** The 
1edc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1edd0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1ede0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1edf0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1ee00 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1ee10 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1ee20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1ee30 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1ee40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1ee50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1ee60 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1ee70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ee80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ee90 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1eea0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1eeb0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1eec0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1eed0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1eee0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1eef0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1ef00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ef10 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1ef20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1ef30 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1ef40 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1ef50 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1ef60 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1ef70 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1ef80 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1ef90 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1efa0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1efb0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1efc0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1efd0 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1efe0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1eff0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1f000 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1f010 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1f020 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1f030 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1f040 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1f050 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1f060 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1f070 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1f080 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1f090 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1f0a0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1f0b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1f0c0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1f0d0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1f0e0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1f0f0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1f100 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
1f110 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1f120 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1f130 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1f140 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1f150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1f160 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1f170 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1f180 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1f190 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1f1a0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1f1b0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1f1c0 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1f1d0 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1f1e0 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1f1f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1f200 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1f210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f220 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1f230 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1f240 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1f250 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1f260 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1f270 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1f280 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1f290 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1f2a0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1f2b0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1f2c0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1f2d0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1f2e0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1f2f0 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d  ULL..** {A13018}
1f300 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1f310 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1f320 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1f330 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1f340 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1f350 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f360 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1f370 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1f380 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1f390 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1f3a0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1f3b0 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1f3c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1f3d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1f3e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1f3f0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1f400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f410 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1f420 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1f430 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1f440 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1f450 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1f460 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1f470 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1f480 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1f490 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1f4a0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1f4b0 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1f4c0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1f4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f4e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1f4f0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1f500 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1f510 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1f520 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1f530 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1f540 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1f550 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1f560 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1f570 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1f580 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
1f590 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1f5a0 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
1f5b0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1f5c0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1f5d0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1f5e0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1f5f0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1f600 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1f610 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1f620 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1f630 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1f640 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1f650 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1f660 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
1f670 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1f680 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1f690 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1f6a0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1f6b0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1f6c0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1f6d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1f6e0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1f6f0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1f700 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1f710 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1f720 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1f730 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1f740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f750 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1f760 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1f770 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1f780 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1f790 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1f7a0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1f7b0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1f7c0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1f7d0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1f7e0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1f7f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1f800 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1f810 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1f820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f830 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1f840 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1f850 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1f860 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1f870 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1f880 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1f890 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1f8a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1f8b0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1f8c0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1f8d0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1f8e0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1f8f0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1f900 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1f910 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1f920 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1f930 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1f940 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1f950 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1f960 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1f970 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1f980 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1f990 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1f9a0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1f9b0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1f9c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1f9d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1f9e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  NTS:.**.** {H130
1f9f0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fa00 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1fa10 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1fa20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1fa30 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1fa40 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1fa50 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1fa60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1fa70 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1fa80 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1fa90 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  F-8..**.** {H130
1faa0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1fab0 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1fac0 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1fad0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1fae0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1faf0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1fb00 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1fb10 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1fb20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1fb30 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1fb40 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1fb50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1fb60 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33  r..**.** {H13013
1fb70 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1fb80 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1fb90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1fba0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1fbb0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1fbc0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1fbd0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1fbe0 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1fbf0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1fc00 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1fc10 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1fc20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1fc30 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nator..**.** {H1
1fc40 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1fc50 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1fc60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fc70 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1fc80 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1fc90 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1fca0 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1fcb0 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1fcc0 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1fcd0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1fce0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1fcf0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1fd00 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {H13015} In [sql
1fd10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fd20 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1fd30 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1fd40 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1fd50 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1fd60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1fd70 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1fd80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1fd90 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1fda0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1fdb0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1fdc0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1fdd0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1fde0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1fdf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1fe00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1fe10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1fe20 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1fe30 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1fe40 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1fe50 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1fe60 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1fe70 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73  .** {H13016} A s
1fe80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1fe90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1fea0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1feb0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1fec0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1fed0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1fee0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1fef0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1ff00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1ff10 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1ff20 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1ff30 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1ff40 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1ff50 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1ff60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1ff70 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1ff80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  nts..**.** {H130
1ff90 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1ffa0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1ffb0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1ffc0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1ffd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1ffe0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1fff0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
20000 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
20010 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  lure..**.** {H13
20020 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
20030 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
20040 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
20050 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
20060 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
20070 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
20080 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
20090 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
200a0 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
200b0 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
200c0 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
200d0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
200e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
200f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20100 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
20110 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
20120 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
20130 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
20140 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
20150 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
20160 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
20170 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
20180 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
20190 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
201a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
201b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
201c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
201d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
201e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
201f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
20200 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
20210 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
20220 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
20230 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
20240 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
20250 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
20260 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
20270 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
20280 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
20290 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
202a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
202b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
202c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
202d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
202e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
202f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
20300 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
20310 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
20320 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
20330 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
20340 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
20350 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
20360 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20370 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
20380 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
20390 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
203a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
203b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
203c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
203d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
203e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
203f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
20400 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
20410 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
20420 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
20430 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
20440 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
20450 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
20460 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
20470 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
20480 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
20490 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
204a0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
204b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
204c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
204d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
204e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
204f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
20500 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
20510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
20520 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
20530 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
20540 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
20550 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20560 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
20570 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
20580 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
20590 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
205a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
205b0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
205c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
205d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
205e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
205f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20600 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
20610 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31  tatement SQL {H1
20620 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a  3100} <H13000>.*
20630 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
20640 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
20650 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
20660 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
20670 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
20680 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
20690 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
206a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
206b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
206c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
206d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
206e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
206f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
20700 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
20710 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
20720 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49  **.** {H13101} I
20730 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
20740 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
20750 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e  d as the argumen
20760 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
20770 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
20780 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
20790 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
207a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
207b0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
207c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
207d0 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20  e16_v2()], then 
207e0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
207f0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
20800 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f      a pointer to
20810 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
20820 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
20830 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
20840 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
20850 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
20860 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
20870 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d  ..**.** {H13102}
20880 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
20890 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
208a0 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  sed as the argum
208b0 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
208c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28     [sqlite3_sql(
208d0 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
208e0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
208f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
20900 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
20910 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20920 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c  16()], then [sql
20930 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75  ite3_sql()] retu
20940 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
20950 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  er..**.** {H1310
20960 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65  3} The string re
20970 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20980 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61  e3_sql(S)] is va
20990 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a  lid until the.**
209a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
209b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
209c0 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
209d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
209e0 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ize(S)]..*/.cons
209f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20a00 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
20a10 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
20a20 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
20a30 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
20a40 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30  ue Object {H1500
20a50 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
20a60 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
20a70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20a80 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
20a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
20aa0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
20ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
20ac0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
20ad0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
20ae0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
20af0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
20b00 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
20b10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
20b20 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
20b30 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
20b40 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72  res. Values stor
20b50 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
20b60 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
20b70 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
20b80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
20b90 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
20ba0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
20bb0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
20bc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
20bd0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
20be0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
20bf0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
20c00 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
20c10 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
20c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
20c30 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
20c40 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
20c50 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
20c60 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
20c70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20c80 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
20c90 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
20ca0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
20cb0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
20cc0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
20cd0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
20ce0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
20cf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
20d00 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
20d10 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
20d20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
20d30 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
20d40 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
20d50 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
20d60 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
20d70 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
20d80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
20d90 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
20da0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
20db0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
20dc0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
20dd0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
20de0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
20df0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
20e00 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
20e10 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
20e20 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
20e30 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
20e40 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
20e50 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
20e60 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
20e70 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
20e80 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
20e90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
20ea0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
20eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
20ec0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
20ed0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
20ee0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
20ef0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
20f00 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
20f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20f20 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
20f30 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
20f40 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
20f50 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
20f60 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
20f70 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
20f80 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
20f90 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
20fa0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
20fb0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
20fc0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
20fd0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
20fe0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20ff0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
21000 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
21010 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
21020 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
21030 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
21040 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
21050 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
21060 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
21070 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
21080 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
21090 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
210a0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68  protected..** Th
210b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
210c0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
210d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
210e0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
210f0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
21100 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
21110 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
21120 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
21130 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
21140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
21150 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
21160 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
21170 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
21180 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
21190 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
211a0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
211b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
211c0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
211d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
211e0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
211f0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
21200 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
21210 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
21220 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
21230 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d   Object {H16001}
21240 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
21250 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
21260 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
21270 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
21280 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
21290 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
212a0 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
212b0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
212c0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
212d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
212e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
212f0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
21300 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21310 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
21320 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
21330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
21340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
21350 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
21360 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
21370 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
21380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
21390 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
213a0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
213b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
213c0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
213d0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
213e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
213f0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
21400 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
21410 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
21420 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
21430 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
21440 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
21450 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
21460 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
21470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21480 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
21490 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
214a0 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20  ements {H13500} 
214b0 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S70300>.** KEYW
214c0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
214d0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
214e0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
214f0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
21500 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
21510 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
21520 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
21530 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
21540 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51  .**.** In the SQ
21550 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20  L strings input 
21560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
21570 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
21580 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
21590 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
215a0 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72  eplaced by a par
215b0 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66  ameter in one of
215c0 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
215d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
215e0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
215f0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
21600 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
21610 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
21620 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
21630 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
21640 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
21650 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
21660 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
21670 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d  VVV is an alpha-
21680 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65  numeric paramete
21690 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75  r name. The valu
216a0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
216b0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
216c0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
216d0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
216e0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
216f0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
21700 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
21710 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21720 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
21730 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
21740 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
21750 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
21760 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
21770 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
21780 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
21790 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
217a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
217b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
217c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
217d0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
217e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
217f0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
21800 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
21810 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
21820 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  .** The leftmost
21830 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
21840 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
21850 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65  .  When the same
21860 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
21870 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
21880 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
21890 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
218a0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
218b0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
218c0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
218d0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
218e0 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66  ..** The index f
218f0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
21900 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
21910 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
21920 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21930 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21940 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
21950 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
21960 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
21970 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
21980 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
21990 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
219a0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
219b0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
219c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
219d0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
219e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
219f0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
21a00 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
21a10 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
21a20 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
21a30 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
21a40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
21a50 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e   In those routin
21a60 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
21a70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
21a80 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
21a90 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
21aa0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
21ab0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
21ac0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
21ad0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21ae0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
21af0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
21b00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
21b10 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66  haracters..** If
21b20 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21b30 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
21b40 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
21b50 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
21b60 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
21b70 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
21b80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
21b90 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
21ba0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
21bb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
21bc0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
21bd0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
21be0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
21bf0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
21c00 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
21c10 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
21c20 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
21c30 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
21c40 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
21c50 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66  h it. If the fif
21c60 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
21c70 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
21c80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
21c90 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
21ca0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
21cb0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
21cc0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
21cd0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
21ce0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
21cf0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
21d00 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
21d10 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
21d20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
21d30 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
21d40 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
21d50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
21d60 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
21d70 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
21d80 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
21d90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
21da0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
21db0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
21dc0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
21dd0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
21de0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
21df0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
21e00 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41   with zeroes.  A
21e10 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
21e20 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
21e30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
21e40 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
21e50 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
21e60 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
21e70 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
21e80 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
21e90 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
21ea0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
21eb0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
21ec0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
21ed0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
21ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
21ef0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
21f00 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
21f10 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67  utines..** A neg
21f20 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
21f30 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
21f40 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
21f50 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
21f60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
21f70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
21f80 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
21f90 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
21fa0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
21fb0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21fc0 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
21fd0 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
21fe0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
21ff0 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e  ep()]..** Bindin
22000 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
22010 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
22020 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
22030 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20  ine..** Unbound 
22040 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
22050 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
22060 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  LL..**.** These 
22070 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22080 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
22090 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72  uccess or an err
220a0 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e  or code if.** an
220b0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
220c0 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47  g.  [SQLITE_RANG
220d0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
220e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
220f0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
22100 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49  of range.  [SQLI
22110 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
22120 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
22130 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c  ) fails..** [SQL
22140 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68  ITE_MISUSE] migh
22150 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
22160 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
22170 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a  are called on a.
22180 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  ** virtual machi
22190 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77  ne that is the w
221a0 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68  rong state or wh
221b0 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20  ich has already 
221c0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  been finalized..
221d0 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20  ** Detection of 
221e0 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69  misuse is unreli
221f0 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69  able.  Applicati
22200 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64  ons should not d
22210 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49  epend.** on SQLI
22220 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e  TE_MISUSE return
22230 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  s.  SQLITE_MISUS
22240 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  E is intended to
22250 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61   indicate a.** a
22260 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
22270 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
22280 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22290 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
222a0 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65  t.** panic rathe
222b0 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51  r than return SQ
222c0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a  LITE_MISUSE..**.
222d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
222e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
222f0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
22300 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22310 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
22320 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
22330 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22340 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22350 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22360 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53   {H13506} The [S
22370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
22380 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65  piler] recognize
22390 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20  s tokens of the 
223a0 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20  forms.**        
223b0 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22    "?", "?NNN", "
223c0 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61  $VVV", ":VVV", a
223d0 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c  nd "@VVV" as SQL
223e0 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20   parameters,.** 
223f0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e           where N
22400 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  NN is any sequen
22410 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
22420 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20  e digits.**     
22430 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56       and where V
22440 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  VV is any sequen
22450 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
22460 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a  e alphanumeric.*
22470 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61  *          chara
22480 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
22490 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
224a0 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f  d by a string co
224b0 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  ntaining.**     
224c0 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61       no spaces a
224d0 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
224e0 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
224f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20  .**.** {H13509} 
22500 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
22510 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
22520 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
22530 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68  *.** {H13512} Th
22540 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
22550 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
22560 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
22570 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
22580 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
22590 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
225a0 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
225b0 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
225c0 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
225d0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
225e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
225f0 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {H13515} The ind
22600 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
22610 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
22620 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
22630 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d  ..**.** {H13518}
22640 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
22650 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
22660 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
22670 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
22680 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
22690 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
226a0 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72   leftmost occurr
226b0 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d  ences of the sam
226c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
226d0 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20  rameter, or one 
226e0 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61  more than the la
226f0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72  rgest index over
22700 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
22710 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
22720 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20  he left if this 
22730 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  is the first occ
22740 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20  urrence.**      
22750 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61      of this para
22760 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74  meter, or 1 if t
22770 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d  his is the leftm
22780 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ost parameter..*
22790 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68  *.** {H13521} Th
227a0 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
227b0 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73   compiler] fails
227c0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
227d0 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20  _RANGE].**      
227e0 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65      error if the
227f0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
22800 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
22810 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20  ss than 1.**    
22820 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72        or greater
22830 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c   than the compil
22840 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41  e-time SQLITE_MA
22850 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
22860 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  R.**          pa
22870 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
22880 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f  H13524} Calls to
22890 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
228a0 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
228b0 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a  nd(S,N,V,...)].*
228c0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
228d0 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56  iate the value V
228e0 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61   with all SQL pa
228f0 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20  rameters having 
22900 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  an.**          i
22910 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65  ndex of N in the
22920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22930 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
22940 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f  H13527} Calls to
22950 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22960 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
22970 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  nd(S,N,...)].** 
22980 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64           overrid
22990 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  e prior calls wi
229a0 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
229b0 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a  es of S and N..*
229c0 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69  *.** {H13530} Bi
229d0 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68  ndings establish
229e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
229f0 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
22a00 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a  e3_bind(S,...)].
22a10 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73  **          pers
22a20 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73  ist across calls
22a30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
22a40 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  et(S)]..**.** {H
22a50 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20  13533} In calls 
22a60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22a70 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
22a80 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
22a90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22aa0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
22ab0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22ad0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53  16(S,N,V,L,D)] S
22ae0 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20  QLite binds the 
22af0 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20  first L.**      
22b00 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65      bytes of the
22b10 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
22b20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c  pointed to by V,
22b30 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20   when L.**      
22b40 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74      is non-negat
22b50 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
22b60 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  36} In calls to 
22b70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22b80 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f  xt(S,N,V,L,D)] o
22b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22ba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22bb0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53  16(S,N,V,L,D)] S
22bc0 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72  QLite binds char
22bd0 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  acters.**       
22be0 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67     from V throug
22bf0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
22c00 20 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20   character when 
22c10 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
22c20 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e  *.** {H13539} In
22c30 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22c40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
22c50 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
22c60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22c70 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
22c80 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
22c90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22ca0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
22cb0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
22cc0 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
22cd0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
22ce0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
22cf0 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
22d00 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20   that the value 
22d10 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  V.**          is
22d20 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20   held in static 
22d30 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
22d40 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68  that will not ch
22d50 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
22d60 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
22d70 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64  time of the bind
22d80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ing..**.** {H135
22d90 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  42} In calls to 
22da0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22db0 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
22dc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
22dd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
22de0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
22df0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22e00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
22e10 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
22e20 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
22e30 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
22e40 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54  nstant [SQLITE_T
22e50 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72  RANSIENT], the r
22e60 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a  outine makes a.*
22e70 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61  *          priva
22e80 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76  te copy of the v
22e90 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74  alue V before it
22ea0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
22eb0 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c  {H13545} In call
22ec0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22ed0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
22ee0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
22ef0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22f00 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
22f10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
22f20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22f30 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
22f40 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69   when D is a poi
22f50 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  nter to.**      
22f60 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20      a function, 
22f70 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
22f80 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  hat function to 
22f90 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20  destroy the.**  
22fa0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20          value V 
22fb0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
22fc0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
22fd0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
22fe0 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73  H13548} In calls
22ff0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
23000 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56  d_zeroblob(S,N,V
23010 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62  ,L)] the value b
23020 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ound.**         
23030 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20   is a BLOB of L 
23040 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f  bytes, or a zero
23050 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20  -length BLOB if 
23060 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
23070 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e  *.** {H13551} In
23080 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23090 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c  e3_bind_value(S,
230a0 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75  N,V)] the V argu
230b0 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20  ment may.**     
230c0 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61       be either a
230d0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
230e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
230f0 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20  t or an.**      
23100 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64      [unprotected
23110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23120 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
23130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
23140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23150 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
23160 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
23170 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
23180 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
23190 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
231a0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
231b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
231c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
231d0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
231e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
231f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
23200 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
23210 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
23220 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
23230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23240 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
23250 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
23260 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
23270 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
23280 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
23290 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
232a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
232b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
232c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
232d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
232e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
232f0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
23300 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
23310 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
23320 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
23330 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
23340 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23350 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
23360 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
23370 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
23380 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37  ers {H13600} <S7
23390 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
233a0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
233b0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
233c0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
233d0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
233e0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
233f0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
23400 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
23410 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
23420 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
23430 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
23440 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
23450 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
23460 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
23470 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
23480 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
23490 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
234a0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
234b0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
234c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
234d0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
234e0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
234f0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
23500 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
23510 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
23520 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
23530 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
23540 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
23550 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
23560 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
23570 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
23580 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
23590 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
235a0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
235b0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
235c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
235d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
235e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
235f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23600 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
23610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
23620 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
23630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
23640 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
23650 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3601} The [sqlit
23660 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23670 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  r_count(S)] inte
23680 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
23690 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61            the la
236a0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61  rgest index of a
236b0 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
236c0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
236d0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
236e0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
236f0 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20  0 if S contains 
23700 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
23710 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
23720 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23730 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
23740 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
23750 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
23760 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
23770 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30   {H13620} <S7030
23780 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
23790 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
237a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
237b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a  ame of the n-th.
237c0 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  ** [SQL paramete
237d0 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  r] in a [prepare
237e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
237f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
23800 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
23810 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
23820 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
23830 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
23840 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
23850 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
23860 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
23870 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
23880 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
23890 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
238a0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
238b0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
238c0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
238d0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
238e0 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
238f0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
23900 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
23910 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
23920 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
23930 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66  and are also ref
23940 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f  erred to as "ano
23950 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
23960 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  s"..**.** The fi
23970 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
23980 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
23990 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
239a0 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  ** If the value 
239b0 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  n is out of rang
239c0 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68  e or if the n-th
239d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
239e0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
239f0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
23a00 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
23a10 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
23a20 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
23a30 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
23a40 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
23a50 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
23a60 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
23a70 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
23a80 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
23a90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
23aa0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
23ab0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
23ac0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23ad0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
23ae0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
23af0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23b00 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
23b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
23b20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
23b30 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
23b40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
23b50 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
23b60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23b70 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
23b80 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23b90 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38           a UTF-8
23ba0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
23bb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
23bc0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  L parameter in.*
23bd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
23be0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23bf0 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64  nt] S having ind
23c00 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ex N, or.**     
23c10 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65       NULL if the
23c20 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72  re is no SQL par
23c30 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
23c40 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  x N or if the.**
23c50 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
23c60 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
23c70 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73   is an anonymous
23c80 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a   parameter "?"..
23c90 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
23ca0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23cb0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
23cc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
23cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23ce0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
23cf0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
23d00 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d  en Name {H13640}
23d10 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
23d20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
23d30 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
23d40 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
23d50 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
23d60 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
23d70 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
23d80 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
23d90 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
23da0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
23db0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
23dc0 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
23dd0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
23de0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
23df0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
23e00 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
23e10 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
23e20 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
23e30 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
23e40 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
23e50 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
23e60 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
23e70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
23e80 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
23e90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23ea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23eb0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
23ec0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
23ed0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
23ee0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
23ef0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23f00 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
23f10 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23f20 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34  TS:.**.** {H1364
23f30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
23f40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
23f50 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ndex(S,N)] inter
23f60 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23f70 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64           the ind
23f80 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
23f90 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70  ter in the [prep
23fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23fb0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68  **          S wh
23fc0 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73  ose name matches
23fd0 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e   the UTF-8 strin
23fe0 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65  g N, or 0 if the
23ff0 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  re is.**        
24000 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69    no match..*/.i
24010 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24020 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
24030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
24040 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
24050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24060 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
24070 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
24080 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
24090 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e  H13660} <S70300>
240a0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
240b0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
240c0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
240d0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
240e0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
240f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
24100 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
24110 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
24120 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55  statement]..** U
24130 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
24140 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
24150 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
24160 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
24170 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
24180 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  13661} The [sqli
24190 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
241a0 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  gs(S)] interface
241b0 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a   resets all SQL.
241c0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
241d0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69  meter bindings i
241e0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
241f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63  statement] S bac
24200 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  k to NULL..*/.in
24210 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
24220 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
24230 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
24240 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
24250 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
24260 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
24270 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  710} <S10700>.**
24280 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
24290 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
242a0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
242b0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
242c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
242d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
242e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
242f0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
24300 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
24310 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
24320 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
24330 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
24340 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  DATE])..**.** IN
24350 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24360 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71  {H13711} The [sq
24370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
24380 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
24390 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
243a0 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
243b0 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68     columns in th
243c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e  e result set gen
243d0 65 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70  erated by the [p
243e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
243f0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
24400 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73    or 0 if S does
24410 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20   not generate a 
24420 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
24430 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24440 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
24450 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
24460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24470 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
24480 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
24490 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  720} <S10700>.**
244a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
244b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
244c0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
244d0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
244e0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
244f0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
24500 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
24510 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
24520 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
24530 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24540 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24550 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24560 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
24570 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
24580 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
24590 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
245a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
245b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
245c0 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20  ing.  The first 
245d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
245e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
245f0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
24600 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
24610 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
24620 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
24630 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
24640 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
24650 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
24660 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
24670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
24680 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
24690 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
246a0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
246b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
246c0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
246d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
246e0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
246f0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
24700 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
24710 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
24720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24730 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
24740 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
24750 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
24760 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
24770 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
24780 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
24790 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
247a0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
247b0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
247c0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
247d0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
247e0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
247f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
24800 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
24810 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
24820 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
24830 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
24840 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
24850 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
24860 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
24870 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
24880 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
24890 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
248a0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
248b0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
248c0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
248d0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
248e0 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  xt..**.** INVARI
248f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
24900 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  721} A successfu
24910 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
24920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
24930 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a  umn_name(S,N)].*
24940 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24950 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24960 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68   name of the Nth
24970 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
24980 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24990 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
249a0 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
249b0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a  ult set of the.*
249c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
249d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
249e0 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  S as a zero-term
249f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
24a00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ing..**.** {H137
24a10 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  23} A successful
24a20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
24a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24a40 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a  mn_name16(S,N)].
24a50 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
24a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24a70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74  e name of the Nt
24a80 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20  h column (where 
24a90 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  0 is.**         
24aa0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   the leftmost co
24ab0 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65  lumn) for the re
24ac0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a  sult set of the.
24ad0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24af0 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72   S as a zero-ter
24b00 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73  minated UTF-16 s
24b10 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
24b20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
24b30 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
24b40 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b  * {H13724} The [
24b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24b60 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ame()] and [sqli
24b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
24b80 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
24b90 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
24ba0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
24bb0 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e  r if they are un
24bc0 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20  able to.**      
24bd0 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d      allocate mem
24be0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69  ory to hold thei
24bf0 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20  r normal return 
24c00 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  strings..**.** {
24c10 48 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e  H13725} If the N
24c20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
24c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24c40 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  me(S,N)] or.**  
24c50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24c60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
24c70 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72  ,N)] is out of r
24c80 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ange, then the.*
24c90 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24ca0 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
24cb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
24cc0 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20  ** {H13726} The 
24cd0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
24ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
24cf0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61  umn_name(S,N)] a
24d00 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
24d10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24d20 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20  ame16(S,N)] are 
24d30 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
24d40 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  next.**         
24d50 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
24d60 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65  routine with the
24d70 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61   same S and N pa
24d80 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
24d90 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73       or until [s
24da0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24db0 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
24dc0 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68  *.** {H13727} Wh
24dd0 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  en a result colu
24de0 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  mn of a [SELECT]
24df0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61   statement conta
24e00 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
24e10 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68  an AS clause, th
24e20 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63  e name of that c
24e30 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65  olumn is the ide
24e40 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20  ntifier.**      
24e50 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74      to the right
24e60 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f   of the AS keywo
24e70 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  rd..*/.const cha
24e80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
24e90 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
24ea0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
24eb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24ec0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
24ed0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24ee0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
24ef0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
24f00 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
24f10 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30  y Result {H13740
24f20 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
24f30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24f40 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
24f50 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
24f60 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
24f70 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
24f80 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
24f90 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43  sult of a [SELEC
24fa0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  T] statement com
24fb0 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20  es from..** The 
24fc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24fd0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
24fe0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
24ff0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
25000 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
25010 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
25020 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
25030 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
25040 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
25050 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
25060 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25070 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
25080 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
25090 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
250a0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
250b0 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
250c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
250d0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
250e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
250f0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
25100 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
25110 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
25120 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
25130 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
25140 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
25150 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
25160 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
25170 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75  * The names retu
25180 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
25190 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
251a0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
251b0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
251c0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
251d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
251e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f  gument to the fo
251f0 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73  llowing calls is
25200 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25210 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
25220 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
25230 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
25240 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
25250 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
25260 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
25270 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
25280 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
25290 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
252a0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
252b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
252c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
252d0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
252e0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
252f0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
25300 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
25310 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
25320 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
25330 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  LL.  These routi
25340 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
25350 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
25360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
25370 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
25380 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68  .  Otherwise, th
25390 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
253a0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
253b0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
253c0 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e  le.** and column
253d0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
253e0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
253f0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
25400 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20  .** As with all 
25410 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
25420 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
25430 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
25440 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
25450 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
25460 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
25470 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
25480 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
25490 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
254a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
254b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
254c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
254d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
254e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
254f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
25500 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
25510 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d  ..**.** {A13751}
25520 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
25530 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
25540 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
25550 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
25560 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
25570 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
25580 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
25590 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
255a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
255b0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
255c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
255d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
255e0 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  741} The [sqlite
255f0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25600 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
25610 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25620 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25630 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
25640 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
25650 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
25660 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
25670 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
25680 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25690 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
256a0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
256b0 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
256c0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
256d0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
256e0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
256f0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25700 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25710 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25720 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
25730 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25740 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b  * {H13742} The [
25750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25760 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53  atabase_name16(S
25770 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25780 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
25790 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
257a0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
257b0 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
257c0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
257d0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  he database.**  
257e0 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69          from whi
257f0 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
25800 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
25810 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25820 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20  ent] S is.**    
25830 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c        extracted,
25840 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
25850 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
25860 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
25870 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
25880 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
25890 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
258a0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
258b0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
258c0 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3743} The [sqlit
258d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
258e0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
258f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
25900 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25910 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
25920 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
25930 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d  f the table from
25940 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
25950 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
25960 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
25970 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25980 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
25990 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
259a0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
259b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
259c0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
259d0 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
259e0 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
259f0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25a00 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
25a10 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
25a20 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3744} The [sqlit
25a30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
25a40 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
25a50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25a60 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25a70 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
25a80 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
25a90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25aa0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
25ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
25ac0 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
25ad0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25ae0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25af0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a  tatement] S is.*
25b00 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61  *          extra
25b10 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
25b20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25b30 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
25b40 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25b50 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25b60 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25b70 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
25b80 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25b90 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b  * {H13745} The [
25ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
25bb0 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  rigin_name(S,N)]
25bc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25bd0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25be0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
25bf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25c00 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
25c10 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
25c20 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
25c30 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
25c40 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
25c50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25c60 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
25c70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
25c80 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
25c90 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
25ca0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
25cb0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
25cc0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
25cd0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
25ce0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
25cf0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
25d00 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
25d10 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
25d20 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
25d30 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
25d40 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25d50 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
25d60 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
25d70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
25d80 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
25d90 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
25da0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
25db0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
25dc0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  mn of the.**    
25dd0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25de0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
25df0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
25e00 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
25e10 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
25e20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
25e30 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
25e40 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
25e50 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
25e60 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
25e70 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
25e80 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20  ** {H13748} The 
25e90 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72  return values fr
25ea0 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
25eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25ec0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
25ed0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
25ee0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
25ef0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
25f00 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
25f10 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
25f20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
25f30 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
25f40 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
25f50 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
25f60 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
25f70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
25f80 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
25f90 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
25fa0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
25fb0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  lumn..**.** ASSU
25fc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
25fd0 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  A13751} If two o
25fe0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
25ff0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
26000 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
26010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
26020 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
26030 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
26040 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
26050 20 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65      for the same
26060 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26070 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
26080 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
26090 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20      at the same 
260a0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
260b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
260c0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
260d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
260e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
260f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26100 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
26110 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26120 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
26130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26140 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
26150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26160 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
26170 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26180 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26190 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
261a0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
261b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
261c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
261d0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
261e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
261f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
26200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26210 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
26220 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26240 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
26250 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
26260 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20  Result {H13760} 
26270 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
26280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26290 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
262a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
262b0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
262c0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
262d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
262e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
262f0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
26300 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26310 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
26320 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
26330 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
26340 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
26350 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
26360 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
26370 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
26380 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
26390 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
263a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
263b0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
263c0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
263d0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
263e0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
263f0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
26400 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
26410 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
26420 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ed. {END}.**.** 
26430 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
26440 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26450 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
26460 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
26470 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
26480 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
26490 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
264a0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
264b0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
264c0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
264d0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
264e0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
264f0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
26500 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
26510 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
26520 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
26530 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
26540 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
26550 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
26560 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
26570 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
26580 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
26590 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
265a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
265b0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
265c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
265d0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
265e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
265f0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
26600 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
26610 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
26620 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
26630 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
26640 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
26650 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
26660 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
26670 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26680 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
26690 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
266a0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
266b0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
266c0 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  e values..**.** 
266d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
266e0 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75  * {H13761}  A su
266f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
26700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26710 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
26720 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
26730 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
26740 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
26750 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
26760 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
26770 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  type.**         
26780 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63    of the table c
26790 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61  olumn that appea
267a0 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f  rs as the Nth co
267b0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a  lumn (numbered.*
267c0 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  *           from
267d0 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c   0) of the resul
267e0 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72  t set to the [pr
267f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26800 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ] S..**.** {H137
26810 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  62}  A successfu
26820 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
26830 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
26840 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  pe16(S,N)].**   
26850 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
26860 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26870 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
26880 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
26890 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  g.**           c
268a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
268b0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20  clared datatype 
268c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
268d0 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
268e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
268f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26900 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30  (numbered from 0
26910 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
26920 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  set to the.**   
26930 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
26950 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20  **.** {H13763}  
26960 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
26970 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61  n 0 or N is grea
26980 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ter than or equa
26990 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
269a0 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20    the number of 
269b0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b  columns in the [
269c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269d0 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20  nt] S,.**       
269e0 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74      or if the Nt
269f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
26a00 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
26a10 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65  r subquery rathe
26a20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
26a30 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75  han a table colu
26a40 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  mn, or if a memo
26a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
26a60 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  ilure.**        
26a70 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
26a80 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72   encoding conver
26a90 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20  sions, then.**  
26aa0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74           calls t
26ab0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
26ac0 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d  n_decltype(S,N)]
26ad0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
26ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26af0 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
26b00 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a  ] return NULL..*
26b10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
26b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26b30 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
26b40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26b50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26b60 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
26b70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26b80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26b90 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
26ba0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
26bb0 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e  H13200} <S10000>
26bc0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
26bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26be0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
26bf0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
26c00 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
26c10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26c20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26c30 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
26c40 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
26c50 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
26c60 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
26c70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26c80 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
26c90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
26ca0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
26cb0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
26cc0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
26cd0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
26ce0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
26cf0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
26d00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
26d10 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
26d20 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
26d30 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
26d40 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
26d50 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
26d60 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
26d70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26d80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
26d90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
26da0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
26db0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
26dc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26dd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26de0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
26df0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
26e00 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
26e10 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
26e20 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
26e30 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
26e40 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
26e50 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
26e60 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
26e70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
26e80 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26e90 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
26ea0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
26eb0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
26ec0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
26ed0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
26ee0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
26ef0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
26f00 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
26f10 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
26f20 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
26f30 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
26f40 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
26f50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
26f60 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
26f70 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
26f80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
26f90 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
26fa0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
26fb0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
26fc0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
26fd0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
26fe0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
26ff0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
27000 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
27010 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
27020 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
27030 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
27040 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
27050 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
27060 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
27070 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
27080 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
27090 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
270a0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
270b0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
270c0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
270d0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
270e0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
270f0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
27100 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
27110 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
27120 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
27130 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
27140 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
27150 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
27160 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
27170 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
27180 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
27190 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
271a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
271b0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
271c0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
271d0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
271e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
271f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
27200 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27210 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
27220 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
27230 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
27240 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
27250 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
27260 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
27270 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
27280 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
27290 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
272a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
272b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
272c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
272d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
272e0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
272f0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
27300 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
27310 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
27320 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
27330 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
27340 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
27350 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
27360 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
27370 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
27380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
27390 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
273a0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
273b0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
273c0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
273d0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
273e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
273f0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
27400 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
27410 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
27420 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
27430 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
27440 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
27450 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
27460 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
27470 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
27480 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
27490 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
274a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
274b0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
274c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
274d0 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22  t].  In the "v2"
274e0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
274f0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
27500 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
27510 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
27520 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
27530 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
27540 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
27550 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
27560 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
27570 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
27580 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
27590 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
275a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
275b0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
275c0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
275d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
275e0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
275f0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
27600 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
27610 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
27620 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
27630 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
27640 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
27650 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
27660 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27670 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
27680 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
27690 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
276a0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
276b0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
276c0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
276d0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
276e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
276f0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
27700 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
27710 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
27720 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
27730 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
27740 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
27750 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
27760 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
27770 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
27780 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
27790 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
277a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
277b0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
277c0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
277d0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
277e0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
277f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
27800 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
27810 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
27820 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
27830 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
27840 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
27850 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
27860 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
27870 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
27880 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
27890 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
278a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
278b0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
278c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
278d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
278e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
278f0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
27900 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
27910 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
27920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27930 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
27940 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
27950 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
27960 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
27970 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
27980 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
27990 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
279a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
279b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
279c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
279d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32  NTS:.**.** {H132
279e0 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65  02}  If the [pre
279f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27a00 20 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62   S is ready to b
27a10 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  e run, then.**  
27a20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27a30 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e  3_step(S)] advan
27a40 63 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65  ces that prepare
27a50 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69  d statement unti
27a60 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  l.**           c
27a70 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74  ompletion or unt
27a80 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74  il it is ready t
27a90 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72  o return another
27aa0 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20   row of the.**  
27ab0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
27ac0 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e  set, or until an
27ad0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
27ae0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
27af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
27b00 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
27b10 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
27b20 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61  {H15304}  When a
27b30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27b40 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65  3_step(S)] cause
27b50 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
27b60 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
27b70 20 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e          S to run
27b80 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20   to completion, 
27b90 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
27ba0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  urns [SQLITE_DON
27bb0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  E]..**.** {H1530
27bc0 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  6}  When a call 
27bd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27be0 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75  (S)] stops becau
27bf0 73 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74  se it is ready t
27c00 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  o.**           r
27c10 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
27c20 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
27c30 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20  set, it returns 
27c40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a  [SQLITE_ROW]..**
27c50 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66  .** {H15308}  If
27c60 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
27c70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63  te3_step(S)] enc
27c80 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20  ounters an.**   
27c90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27ca0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
27cb0 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
27cc0 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20  -time error,.** 
27cd0 20 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74            it ret
27ce0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
27cf0 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  ate error code t
27d00 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  hat is not one o
27d10 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  f.**           [
27d20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c  SQLITE_OK], [SQL
27d30 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51  ITE_ROW], or [SQ
27d40 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
27d50 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61  * {H15310}  If a
27d60 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
27d70 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
27d80 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20  ] or a run-time 
27d90 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
27da0 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
27db0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
27dc0 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20  te3_step(S)].** 
27dd0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
27de0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27df0 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75  ent] S created u
27e00 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
27e10 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61    legacy interfa
27e20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
27e30 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
27e40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27e50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
27e60 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
27e70 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27e80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
27e90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51  LITE_ERROR], [SQ
27ea0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b  LITE_BUSY], or [
27eb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
27ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
27ed0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
27ee0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27ef0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
27f00 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
27f10 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20  lt set {H13770} 
27f20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S10700>.**.** R
27f30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
27f40 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
27f50 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
27f60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27f70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
27f80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37  TS:.**.** {H1377
27f90 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
27fa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
27fb0 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
27fc0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ns [SQLITE_ROW],
27fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
27fe0 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
27ff0 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
28000 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
28010 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20  e same value.** 
28020 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
28030 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28040 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74  _count(S)] funct
28050 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ion..**.** {H137
28060 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69  72}  After [sqli
28070 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
28080 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61   returned any va
28090 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
280a0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
280b0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f  ITE_ROW] or befo
280c0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
280d0 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  (S)] has been ca
280e0 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20  lled on the.**  
280f0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
28100 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f  ed statement] fo
28110 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  r the first time
28120 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a   since it was.**
28130 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
28140 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
28150 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69  epared] or [sqli
28160 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65  te3_reset | rese
28170 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t],.**          
28180 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
28190 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
281a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
281b0 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
281c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
281d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
281e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
281f0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
28200 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
28210 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
28220 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
28230 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
28240 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
28250 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
28260 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
28270 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
28280 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
28290 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
282a0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
282b0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
282c0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
282d0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
282e0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
282f0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
28300 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
28310 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
28320 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
28330 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
28340 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
28350 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
28360 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
28370 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
28380 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
28390 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
283a0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
283b0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
283c0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
283d0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
283e0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
283f0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
28400 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
28410 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
28420 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
28430 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
28440 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
28450 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
28460 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
28470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
28480 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
28490 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
284a0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
284b0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
284c0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
284d0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
284e0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
284f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
28500 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
28510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
28520 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
28530 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
28540 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
28550 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
28560 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
28570 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28580 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
28590 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
285a0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
285b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
285c0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
285d0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
285e0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
285f0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
28600 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
28610 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
28620 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
28630 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
28640 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
28650 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28660 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
28670 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
28680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
28690 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
286a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
286b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
286c0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
286d0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
286e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
286f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
28700 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
28710 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
28720 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
28730 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
28740 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
28750 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28760 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
28770 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
28780 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
28790 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
287a0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
287b0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
287c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
287d0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
287e0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
287f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
28800 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
28810 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
28820 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
28830 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
28840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28850 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
28860 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
28870 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
28880 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
28890 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
288a0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
288b0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
288c0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
288d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
288e0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
288f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28900 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
28910 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28920 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
28930 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
28940 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
28950 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
28960 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
28970 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
28980 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
28990 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
289a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
289b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
289c0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
289d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
289e0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
289f0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
28a00 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
28a10 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
28a20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28a30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28a40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
28a50 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
28a60 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
28a70 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
28a80 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
28a90 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
28aa0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
28ab0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
28ac0 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
28ad0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
28ae0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
28af0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
28b00 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
28b10 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
28b20 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
28b30 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
28b40 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
28b50 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28b60 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
28b70 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
28b80 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
28b90 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
28ba0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
28bb0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
28bc0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
28bd0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
28be0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
28bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28c00 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
28c10 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
28c20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
28c30 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
28c40 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
28c50 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
28c60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
28c70 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
28c80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
28c90 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
28ca0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
28cb0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
28cc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
28cd0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28ce0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28cf0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
28d00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
28d10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28d20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
28d30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
28d40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
28d50 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
28d60 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
28d70 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
28d80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28d90 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
28da0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
28db0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
28dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28dd0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
28de0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
28df0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
28e00 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
28e10 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28e20 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
28e30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28e40 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
28e50 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
28e60 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
28e70 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
28e80 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
28e90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
28ea0 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
28eb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
28ec0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
28ed0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
28ee0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
28ef0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
28f00 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
28f10 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
28f20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
28f30 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
28f40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28f50 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
28f60 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
28f70 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
28f80 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
28f90 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
28fa0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
28fb0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
28fc0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
28fd0 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
28fe0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
28ff0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
29000 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
29010 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
29020 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
29030 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
29040 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
29050 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
29060 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
29070 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
29080 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
29090 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
290a0 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
290b0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
290c0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
290d0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
290e0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
290f0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
29100 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
29110 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
29120 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29130 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
29140 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
29150 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29160 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
29170 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
29180 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
29190 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
291a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
291b0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
291c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
291d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
291e0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
291f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
29200 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
29210 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
29220 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
29230 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
29240 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
29250 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
29260 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
29270 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
29280 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
29290 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
292a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
292b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
292c0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
292d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
292e0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
292f0 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
29300 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
29310 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
29320 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
29330 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
29340 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
29350 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
29360 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
29370 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
29380 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
29390 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
293a0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
293b0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
293c0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
293d0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
293e0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
293f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
29400 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
29410 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
29420 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
29430 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
29440 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
29450 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
29460 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29470 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
29480 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
29490 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
294a0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
294b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
294c0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
294d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
294e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
294f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29500 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29510 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
29520 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29530 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29540 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29550 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29560 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29570 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
29580 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
29590 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
295a0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
295b0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
295c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
295d0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
295e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
295f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29600 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
29610 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
29620 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
29630 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
29640 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
29650 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
29660 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
29670 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29680 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
29690 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
296a0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
296b0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
296c0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
296d0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
296e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
296f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29700 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
29710 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
29720 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
29730 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
29740 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
29750 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29760 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29770 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
29780 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29790 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
297a0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
297b0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
297c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
297d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
297e0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
297f0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
29800 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
29810 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
29820 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29830 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
29840 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
29850 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
29860 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
29870 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
29880 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
29890 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
298a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
298b0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
298c0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
298d0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
298e0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
298f0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
29900 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
29910 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
29920 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
29930 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
29940 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
29950 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
29960 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
29970 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
29980 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
29990 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
299a0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
299b0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
299c0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
299d0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
299e0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
299f0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29a00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
29a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29a20 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
29a30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
29a40 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
29a50 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
29a60 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
29a70 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
29a80 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
29a90 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
29aa0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
29ab0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
29ac0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29ad0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
29ae0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
29af0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
29b00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
29b10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29b20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
29b30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
29b40 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
29b50 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
29b60 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
29b70 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29b80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29b90 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
29ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29bb0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
29bc0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
29bd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
29be0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
29bf0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
29c00 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
29c10 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
29c20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29c30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
29c40 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
29c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29c60 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
29c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29c80 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
29c90 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29ca0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29cb0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
29cc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
29cd0 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
29ce0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
29cf0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
29d00 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
29d10 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
29d20 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
29d30 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
29d40 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
29d50 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
29d60 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
29d70 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
29d80 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
29d90 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
29da0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
29db0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
29dc0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
29dd0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
29de0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
29df0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
29e00 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
29e10 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
29e20 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
29e30 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
29e40 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
29e50 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
29e60 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
29e70 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
29e80 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
29e90 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
29ea0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
29eb0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
29ec0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
29ed0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
29ee0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
29ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29f00 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
29f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29f20 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
29f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29f40 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
29f50 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
29f60 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
29f70 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
29f80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29f90 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
29fa0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
29fb0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
29fc0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
29fd0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
29fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29ff0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2a000 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a010 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2a020 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2a030 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2a040 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2a050 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2a060 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2a070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a080 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2a090 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2a0a0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2a0b0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2a0c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2a0d0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2a0f0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2a100 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2a110 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2a120 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2a130 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2a140 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2a150 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2a160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a170 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
2a180 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2a190 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2a1a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2a1b0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2a1c0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2a1d0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2a1e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2a1f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a200 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2a210 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2a220 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
2a230 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2a240 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2a250 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2a260 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2a270 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2a280 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2a290 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2a2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a2b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2a2c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2a2d0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2a2e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2a2f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
2a300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2a310 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2a320 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2a330 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2a340 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2a350 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2a360 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2a370 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2a380 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2a390 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2a3a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2a3b0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2a3c0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2a3d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2a3e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2a3f0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2a400 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2a410 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
2a420 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2a430 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  13803} The [sqli
2a440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a450 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a460 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a470 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a480 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a490 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a4a0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a4b0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a4c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a4d0 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ] S into a BLOB 
2a4e0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2a4f0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
2a500 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
2a510 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
2a520 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68  *.** {H13806} Th
2a530 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a540 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e  n_bytes(S,N)] in
2a550 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a560 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a570 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a580 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
2a590 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2a5a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2a5b0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2a5c0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2a5d0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2a5e0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2a5f0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2a600 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2a610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a620 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
2a630 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2a640 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
2a650 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d  ..**.** {H13809}
2a660 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a670 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e  lumn_bytes16(S,N
2a680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2a690 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2a6a0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2a6b0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2a6c0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2a6d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a6e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2a6f0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2a700 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2a710 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2a720 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2a730 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a740 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a750 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  S,N)]..**.** {H1
2a760 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3812} The [sqlit
2a770 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
2a780 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a790 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2a7a0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2a7b0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2a7c0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2a7d0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2a7e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2a7f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a800 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
2a810 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2a820 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2a830 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2a840 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2a850 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68  *.** {H13815} Th
2a860 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a870 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
2a880 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2a890 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2a8a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2a8b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2a8c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2a8d0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a8e0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a8f0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2a900 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2a910 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2a920 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
2a930 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
2a940 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2a950 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d  ..**.** {H13818}
2a960 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a970 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
2a980 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2a990 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2a9a0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2a9b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a9c0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a9d0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2a9e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2a9f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2aa00 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2aa10 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2aa20 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2aa30 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2aa40 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2aa50 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b  * {H13821} The [
2aa60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2aa70 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ext(S,N)] interf
2aa80 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2aa90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2aaa0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2aab0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2aac0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2aad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2aae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aaf0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
2ab00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2ab10 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
2ab20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ab30 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ab40 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ab50 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65  .** {H13824} The
2ab60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ab70 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e  _text16(S,N)] in
2ab80 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2ab90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2aba0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2abb0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2abc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2abd0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2abe0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2abf0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2ac00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2ac10 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2ac20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2ac30 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2ac40 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e   order string an
2ac50 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  d returns.**    
2ac60 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
2ac70 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2ac80 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54  **.** {H13827} T
2ac90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2aca0 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e  mn_type(S,N)] in
2acb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2acc0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2acd0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2ace0 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2acf0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2ad00 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2ad10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2ad20 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2ad30 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2ad40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2ad50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e  he Nth column in
2ad60 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2ad70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2ad80 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2ad90 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2ada0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2adb0 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68  *.** {H13830} Th
2adc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2add0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
2ade0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2adf0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
2ae00 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
2ae10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ae20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2ae30 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2ae40 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2ae50 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2ae60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2ae70 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2ae80 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2ae90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2aea0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2aeb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2aec0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2aed0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2aee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2aef0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
2af00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2af10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2af20 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2af30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2af40 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
2af50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
2af60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2af70 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2af80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2af90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2afa0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2afb0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2afc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
2afd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2afe0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
2aff0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2b000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b010 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2b020 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2b030 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2b040 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
2b050 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b060 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2b070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2b080 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b090 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
2b0a0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
2b0b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
2b0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b0d0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
2b0e0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
2b0f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2b100 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
2b110 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53  3300} <S70300><S
2b120 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
2b130 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2b140 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2b150 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2b160 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b170 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2b180 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2b190 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
2b1a0 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78  sfully or not ex
2b1b0 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
2b1c0 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  hen.** SQLITE_OK
2b1d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66   is returned. If
2b1e0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
2b1f0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
2b200 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
2b210 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
2b220 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2b230 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2b240 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b250 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2b260 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2b270 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
2b280 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
2b290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b2a0 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  t].  If the virt
2b2b0 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
2b2c0 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  not.** completed
2b2d0 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
2b2e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2b2f0 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
2b300 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
2b310 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
2b320 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
2b330 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
2b340 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  pt]..** Incomple
2b350 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
2b360 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
2b370 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
2b380 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65  anceled,.** depe
2b390 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72  nding on the cir
2b3a0 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20  cumstances, and 
2b3b0 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  the.** [error co
2b3c0 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
2b3d0 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
2b3e0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  RT]..**.** INVAR
2b3f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2b400 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1302} The [sqlit
2b410 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
2b420 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f  interface destro
2b430 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ys the.**       
2b440 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2b450 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65  tement] S and re
2b460 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20  leases all.**   
2b470 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e         memory an
2b480 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73  d file resources
2b490 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62   held by that ob
2b4a0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ject..**.** {H11
2b4b0 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  304} If the most
2b4c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2b4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b4e0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
2b4f0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2b500 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
2b510 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a  urned an error,.
2b520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2b530 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b540 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74  ze(S)] returns t
2b550 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a  hat same error..
2b560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2b570 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2b580 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2b5a0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2b5b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2b5c0 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30   {H13330} <S7030
2b5d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2b5e0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2b5f0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2b600 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2b610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2b620 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2b630 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2b640 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2b650 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2b660 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
2b670 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
2b680 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
2b690 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
2b6a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2b6b0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2b6c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
2b6d0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
2b6e0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
2b6f0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2b700 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
2b710 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
2b720 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20  .**.** {H11332} 
2b730 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2b740 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2b750 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2b760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b770 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
2b780 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2b790 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2b7a0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ram..**.** {H113
2b7b0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
2b7c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2b7d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b7e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2b7f0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2b800 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2b810 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2b820 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2b830 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
2b840 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2b850 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2b860 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2b870 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
2b880 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
2b890 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2b8a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2b8b0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  K]..**.** {H1133
2b8c0 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
2b8d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2b8e0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b8f0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2b900 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2b910 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2b920 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2b930 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
2b940 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b950 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2b960 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2b970 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48   code]..**.** {H
2b980 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
2b990 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2b9a0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
2b9b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2b9c0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
2b9d0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2b9e0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2b9f0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2ba00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ba10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ba20 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2ba30 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2ba40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2ba50 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2ba60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
2ba70 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16100} <S20200>
2ba80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
2ba90 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2baa0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
2bab0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2bac0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bad0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
2bae0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2baf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bb00 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2bb10 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
2bb20 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2bb30 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2bb40 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2bb50 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2bb60 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2bb70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2bb80 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2bb90 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2bba0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2bbb0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2bbc0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2bbd0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2bbe0 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
2bbf0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
2bc00 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
2bc10 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
2bc20 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
2bc30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2bc40 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
2bc50 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
2bc60 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2bc70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
2bc80 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
2bc90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bca0 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
2bcb0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2bcc0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2bcd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bce0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2bcf0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2bd00 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2bd10 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   If a single pro
2bd20 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
2bd30 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
2bd40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
2bd50 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
2bd60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2bd70 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
2bd80 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
2bd90 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2bda0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
2bdb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2bdc0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2bdd0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2bde0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2bdf0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2be00 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  d.  The length o
2be10 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2be20 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2be30 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
2be40 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
2be50 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
2be60 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
2be70 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2be80 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
2be90 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
2bea0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2beb0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2bec0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2bed0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2bee0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2bef0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
2bf00 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
2bf10 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2bf20 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2bf30 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2bf40 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2bf50 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2bf60 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
2bf70 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2bf80 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2bf90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2bfa0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2bfb0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
2bfc0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2bfd0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
2bfe0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2bff0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2c000 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2c010 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2c020 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2c030 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2c040 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2c050 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
2c060 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2c070 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
2c080 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
2c090 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
2c0a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2c0b0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2c0c0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2c0d0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2c0e0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2c0f0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2c100 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2c110 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
2c120 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
2c130 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c140 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
2c150 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c160 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
2c170 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
2c180 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
2c190 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2c1a0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
2c1b0 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
2c1c0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2c1d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2c1e0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
2c1f0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
2c200 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
2c210 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
2c220 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
2c230 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
2c240 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
2c250 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
2c260 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
2c270 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
2c280 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
2c290 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
2c2a0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
2c2b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2c2c0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
2c2d0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
2c2e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2c2f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
2c300 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
2c310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c320 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
2c330 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
2c340 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
2c350 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
2c360 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
2c370 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
2c380 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
2c390 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
2c3a0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2c3b0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2c3c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2c3d0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2c3e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2c3f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c400 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2c410 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
2c420 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2c430 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2c440 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2c450 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2c460 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
2c470 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
2c480 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2c490 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2c4a0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
2c4b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2c4c0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2c4d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2c4e0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2c4f0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
2c500 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
2c510 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
2c520 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2c530 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2c540 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2c550 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
2c560 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61  hree function ca
2c570 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49  llbacks..**.** I
2c580 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2c590 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2c5a0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2c5b0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2c5c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2c5d0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2c5e0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2c5f0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2c600 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2c610 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2c620 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2c630 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65  codings.  SQLite
2c640 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2c650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c660 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2c670 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2c680 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2c690 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2c6a0 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69  d.  A function i
2c6b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2c6c0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
2c6d0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
2c6e0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
2c6f0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2c700 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2c710 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
2c720 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41  egative nArg.  A
2c730 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2c740 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
2c750 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
2c760 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
2c770 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2c780 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
2c790 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2c7a0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2c7b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2c7c0 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69  t.  .** A functi
2c7d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2c7e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2c7f0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
2c800 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
2c810 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
2c820 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2c830 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2c840 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
2c850 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
2c860 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
2c870 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20  .**.** Built-in 
2c880 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2c890 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
2c8a0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
2c8b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2c8c0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
2c8d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c8e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ed function with
2c8f0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76   a given name ov
2c900 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62  errides all.** b
2c910 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2c920 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  s in the same [d
2c930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c940 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d  on] with the sam
2c950 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65  e name..** Subse
2c960 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  quent applicatio
2c970 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c980 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2c990 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69  name only overri
2c9a0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70  de .** prior app
2c9b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c9c0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2c9d0 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74  are an exact mat
2c9e0 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75  ch for the.** nu
2c9f0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
2ca00 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64  rs and preferred
2ca10 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
2ca20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
2ca30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ca40 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2ca50 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2ca60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2ca70 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2ca80 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2ca90 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2caa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cab0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2cac0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2cad0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2cae0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2caf0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2cb00 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
2cb10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  NTS:.**.** {H161
2cb20 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2cb30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cb40 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  16(D,X,...)] int
2cb50 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 68  erface shall beh
2cb60 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
2cb70 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  as [sqlite3_crea
2cb80 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2cb90 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72 79 20 77  ...)] in every w
2cba0 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
2cbb0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
2cbc0 74 65 72 70 72 65 74 73 20 74 68 65 20 58 20 61  terprets the X a
2cbd0 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d  rgument as zero-
2cbe0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
2cbf0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  6.**          na
2cc00 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2cc10 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65  instead of as ze
2cc20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2cc30 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  F-8..**.** {H161
2cc40 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  06} A successful
2cc50 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2cc60 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2cc70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cc80 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2cc90 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2cca0 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a  shall register.*
2ccb0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65  *          or re
2ccc0 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20  places callback 
2ccd0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
2cce0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ccf0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
2cd00 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70       used to imp
2cd10 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2cd20 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
2cd30 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72  with N parameter
2cd40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
2cd50 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65  d having a prefe
2cd60 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2cd70 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  ng of E..**.** {
2cd80 48 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73  H16109} A succes
2cd90 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2cda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cdb0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2cdc0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2cdd0 20 20 20 20 73 68 61 6c 6c 20 72 65 70 6c 61 63      shall replac
2cde0 65 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61  e the P, F, S, a
2cdf0 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d  nd L values from
2ce00 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
2ce10 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2ce20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c    the same D, X,
2ce30 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73   N, and E values
2ce40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d  ..**.** {H16112}
2ce50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2ce60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ce70 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  X,...)] interfac
2ce80 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  e shall fail.** 
2ce90 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
2cea0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d  SQL function nam
2ceb0 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e X is.**       
2cec0 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32     longer than 2
2ced0 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69  55 bytes exclusi
2cee0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74  ve of the zero t
2cef0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
2cf00 20 7b 48 31 36 31 31 38 7d 20 54 68 65 20 5b 73   {H16118} The [s
2cf10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cf20 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2cf30 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61  ,F,S,L)] interfa
2cf40 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ce.**          s
2cf50 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73  hall fail unless
2cf60 20 65 69 74 68 65 72 20 46 20 69 73 20 4e 55 4c   either F is NUL
2cf70 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2cf80 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a  e non-NULL or.**
2cf90 2a 20 20 20 20 20 20 20 20 20 46 20 69 73 20 6e  *         F is n
2cfa0 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e  on-NULL and S an
2cfb0 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a  d L are NULL..**
2cfc0 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65  .** {H16121} The
2cfd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2cfe0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29  _function(D,...)
2cff0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2d000 6c 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  l fails with an.
2d010 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
2d020 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2d030 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65  E_BUSY] if there
2d040 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64   exist [prepared
2d050 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20   statements].** 
2d060 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
2d070 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2d080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d090 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  n] D..**.** {H16
2d0a0 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2d0b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d0c0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e  n(D,X,N,...)] in
2d0d0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61  terface shall fa
2d0e0 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
2d0f0 20 20 20 20 61 6e 20 65 72 72 6f 72 20 63 6f 64      an error cod
2d100 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
2d110 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72  OR] if parameter
2d120 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20   N is less.**   
2d130 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f         than -1 o
2d140 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2d150 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32  27..**.** {H1612
2d160 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e  7} When N is non
2d170 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b  -negative, the [
2d180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d190 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2d1a0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2d1b0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2d1c0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
2d1d0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2d1e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2d1f0 20 20 20 20 20 53 51 4c 20 66 75 6e 63 74 69 6f       SQL functio
2d200 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2d210 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e  med X when the n
2d220 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2d230 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
2d240 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  nction is.**    
2d250 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e        exactly N.
2d260 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20  .**.** {H16130} 
2d270 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68  When N is -1, th
2d280 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2d290 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2d2a0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2d2b0 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61     interface sha
2d2c0 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  ll register call
2d2d0 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2d2e0 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 0a  ked for the SQL.
2d2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
2d300 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74  tion named X wit
2d310 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2d320 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2d330 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {H16133} When c
2d340 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2d350 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d360 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2d370 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2d380 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2d390 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2d3a0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2d3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2d3c0 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2d3d0 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2d3e0 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2d3f0 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2d400 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2d410 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2d420 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c   non-zero N shal
2d430 6c 20 62 65 20 70 72 65 66 65 72 72 65 64 2e 0a  l be preferred..
2d440 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57  **.** {H16136} W
2d450 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2d460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d470 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
2d480 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2d490 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
2d4a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2d4b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2d4c0 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20  ction X with.** 
2d4d0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
2d4e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2d4f0 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68  ments N but with
2d500 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20   different.**   
2d510 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73         encodings
2d520 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70   E, then the imp
2d530 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72  lementation wher
2d540 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a  e E matches the.
2d550 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
2d560 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 73 68  base encoding sh
2d570 61 6c 6c 20 70 72 65 66 65 72 72 65 64 2e 0a 2a  all preferred..*
2d580 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f  *.** {H16139} Fo
2d590 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53  r an aggregate S
2d5a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  QL function crea
2d5b0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
2d5c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2d5d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2d5e0 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d  ,X,N,E,P,0,S,L)]
2d5f0 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a   the finalizer.*
2d600 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2d610 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61  ion L shall alwa
2d620 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78  ys be invoked ex
2d630 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68  actly once if th
2d640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  e.**          st
2d650 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73  ep function S is
2d660 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2d670 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a  ore times..**.**
2d680 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53   {H16142} When S
2d690 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69  QLite invokes ei
2d6a0 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f  ther the xFunc o
2d6b0 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e  r xStep function
2d6c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2d6d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
2d6e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d6f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2d700 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20   created.**     
2d710 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
2d720 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d730 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d740 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d750 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
2d760 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79    then the array
2d770 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2d780 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73  ue] objects pass
2d790 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ed as the.**    
2d7a0 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61        third para
2d7b0 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65 20 5b  meter shall be [
2d7c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d7d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d7e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d7f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d800 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2d810 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2d820 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2d830 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2d840 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2d850 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2d860 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2d870 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2d880 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2d890 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2d8a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d8b0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2d8c0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2d8d0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2d8e0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2d8f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d900 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2d910 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2d920 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2d930 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2d940 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2d950 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2d960 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2d970 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d980 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2d990 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2d9a0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2d9b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2d9c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2d9d0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2d9e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d9f0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2da00 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
2da10 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53  ings {H10267} <S
2da20 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a  50200> <H16100>.
2da30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2da40 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
2da50 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
2da60 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
2da70 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
2da80 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
2da90 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
2daa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2dab0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
2dac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2dad0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
2dae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2daf0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
2db00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2db10 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
2db20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
2db30 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
2db40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
2db50 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
2db60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2db70 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
2db80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2db90 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2dba0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
2dbb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2dbc0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
2dbd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
2dbe0 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
2dbf0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
2dc00 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2dc10 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
2dc20 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
2dc30 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
2dc40 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2dc50 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
2dc60 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
2dc70 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
2dc80 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
2dc90 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
2dca0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2dcb0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
2dcc0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
2dcd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
2dce0 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
2dcf0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
2dd00 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
2dd10 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
2dd20 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
2dd30 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65  ell you want the
2dd40 79 20 64 6f 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  y do..*/.SQLITE_
2dd50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2dd60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2dd70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2dd80 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
2dd90 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2dda0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2ddb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2ddc0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ddd0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
2dde0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2ddf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2de00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2de10 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2de20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
2de30 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2de40 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2de50 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
2de60 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2de70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2de80 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2de90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2dea0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2deb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2dec0 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2ded0 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
2dee0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2def0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2df00 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2df10 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30  es {H15100} <S20
2df20 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  200>.**.** The C
2df30 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2df40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2df50 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2df60 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2df70 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2df80 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2df90 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2dfa0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2dfb0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2dfc0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2dfd0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2dfe0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2dff0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2e000 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2e010 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2e020 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2e030 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2e040 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e050 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2e060 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2e070 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2e080 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2e090 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2e0a0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
2e0b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2e0c0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2e0d0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2e0e0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2e0f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e100 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2e110 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2e120 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e130 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2e140 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2e150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2e160 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e170 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2e180 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2e190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2e1a0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2e1b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e1c0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2e1d0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2e1e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e1f0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2e200 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2e210 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2e220 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2e230 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2e240 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2e250 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2e260 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
2e270 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2e280 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2e290 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2e2a0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2e2b0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2e2c0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2e2d0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2e2e0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2e2f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e300 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2e310 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2e320 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2e330 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2e340 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2e350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e360 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2e370 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2e380 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
2e390 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
2e3a0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
2e3b0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
2e3c0 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
2e3d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e3e0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2e3f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2e400 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2e410 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2e420 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2e430 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2e440 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2e450 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
2e460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2e470 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2e480 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2e490 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2e4a0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2e4b0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2e4c0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2e4d0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2e4e0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2e4f0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2e500 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2e510 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2e520 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2e530 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2e540 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2e550 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2e560 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2e570 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2e580 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2e590 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2e5a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2e5b0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2e5c0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2e5d0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2e5e0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2e5f0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2e600 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2e610 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2e620 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
2e630 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
2e640 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
2e650 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
2e660 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
2e670 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2e680 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2e690 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2e6a0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
2e6b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2e6c0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
2e6d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
2e6e0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
2e6f0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e700 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2e710 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2e720 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
2e730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e740 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2e750 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e760 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
2e770 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2e780 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2e790 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
2e7a0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2e7b0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
2e7c0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
2e7d0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
2e7e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  rs..**.** INVARI
2e7f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ANTS:.**.** {H15
2e800 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
2e810 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
2e820 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e830 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e840 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e860 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c  ject V into a BL
2e870 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20  OB and then.**  
2e880 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2e890 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2e8a0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2e8b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d  ..**.** {H15106}
2e8c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e8d0 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
2e8e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e8f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e900 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e910 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
2e920 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2e930 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2e940 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2e950 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2e960 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2e970 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2e980 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2e990 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2e9a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2e9b0 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
2e9c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
2e9d0 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
2e9e0 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b  * {H15109} The [
2e9f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2ea00 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
2ea10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
2ea20 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
2ea30 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ea40 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
2ea50 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
2ea60 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
2ea70 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
2ea80 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
2ea90 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2eaa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
2eab0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2eac0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ead0 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
2eae0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2eaf0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2eb00 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2eb10 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
2eb20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  )]..**.** {H1511
2eb30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2eb40 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
2eb50 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2eb60 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2eb70 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2eb80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2eb90 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
2eba0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ebb0 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
2ebc0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
2ebd0 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
2ebe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20  .**.** {H15115} 
2ebf0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2ec00 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
2ec10 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2ec20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2ec30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ec40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2ec50 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2ec60 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2ec70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2ec80 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
2ec90 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
2eca0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2ecb0 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  H15118} The [sql
2ecc0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2ecd0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2ece0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2ecf0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2ed00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ed10 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2ed20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2ed30 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2ed40 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2ed50 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
2ed60 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2ed70 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
2ed80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
2ed90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2eda0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2edb0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2edc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2edd0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2ede0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2edf0 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
2ee00 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2ee10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ee20 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2ee30 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68  *.** {H15124} Th
2ee40 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ee50 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
2ee60 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2ee70 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ee80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ee90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2eea0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2eeb0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2eec0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2eed0 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2eee0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2eef0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2ef00 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2ef10 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2ef20 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2ef30 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
2ef40 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2ef50 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2ef60 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2ef70 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2ef80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ef90 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2efa0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2efb0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2efc0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2efd0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
2efe0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2eff0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2f000 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2f010 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2f020 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
2f030 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f040 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2f050 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2f060 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2f070 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f080 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2f090 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2f0a0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2f0b0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2f0c0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2f0d0 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2f0e0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2f0f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f100 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2f110 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20  ** {H15133} The 
2f120 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2f130 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2f140 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2f150 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2f160 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2f170 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2f180 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2f190 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2f1a0 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2f1b0 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2f1c0 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2f1d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2f1e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f1f0 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
2f200 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
2f210 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2f220 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
2f230 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
2f240 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2f250 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f260 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2f270 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
2f280 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
2f290 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
2f2a0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
2f2b0 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
2f2c0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
2f2d0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
2f2e0 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
2f2f0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2f300 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
2f310 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
2f320 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2f330 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2f340 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
2f350 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
2f360 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2f370 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2f380 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2f390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f3a0 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
2f3b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
2f3c0 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
2f3d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2f3e0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2f3f0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f400 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f410 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f420 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2f430 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2f440 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2f450 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2f460 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2f470 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2f480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2f490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f4a0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2f4b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2f4c0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2f4d0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2f4e0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2f4f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2f500 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2f510 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f520 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2f530 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2f540 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f550 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f560 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f570 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f590 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2f5a0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2f5b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2f5c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2f5d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2f5e0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2f5f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2f600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f610 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2f620 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2f630 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32  t {H16210} <S202
2f640 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d  00>.**.** The im
2f650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f660 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2f670 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2f680 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
2f690 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74  cate.** a struct
2f6a0 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ure for storing 
2f6b0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
2f6c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
2f6d0 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
2f6e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f6f0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
2f700 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72  led for a.** par
2f710 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2f720 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61  e, SQLite alloca
2f730 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65  tes nBytes of me
2f740 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
2f750 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   that.** memory,
2f760 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f770 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e  ointer to it. On
2f780 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2f790 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2f7a0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2f7b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2f7c0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2f7d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2f7e0 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ndex,.** the sam
2f7f0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
2f800 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d  rned. The implem
2f810 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2f820 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
2f830 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65  e.** the returne
2f840 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
2f850 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
2f860 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  ** SQLite automa
2f870 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2f880 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66  e allocated buff
2f890 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  er when the aggr
2f8a0 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63  egate.** query c
2f8b0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2f8c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f8d0 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
2f8e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2f8f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2f900 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2f910 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2f920 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2f930 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
2f940 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2f950 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2f960 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2f970 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2f980 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2f990 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2f9a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2f9b0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2f9c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2f9d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f9e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2f9f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31  S:.**.** {H16211
2fa00 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
2fa10 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
2fa20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2fa30 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
2fa40 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
2fa50 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
2fa60 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
2fa70 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
2fa80 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
2fa90 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
2faa0 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
2fab0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62   to allocate N b
2fac0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a  ytes of memory,.
2fad0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2fae0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
2faf0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
2fb00 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61  er to the alloca
2fb10 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  ted memory..**.*
2fb20 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20  * {H16213} If a 
2fb30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2fb40 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2fb50 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  uring.**        
2fb60 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
2fb70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2fb80 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
2fb90 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a  tion returns 0..
2fba0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53  **.** {H16215} S
2fbb0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2fbc0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
2fbd0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2fbe0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2fbf0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2fc00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f   for the same co
2fc10 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a  ntext pointer C.
2fc20 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f  **          igno
2fc30 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  re the N paramet
2fc40 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  er and return a 
2fc50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
2fc60 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
2fc70 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
2fc80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2fc90 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2fca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d  ..**.** {H16217}
2fcb0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
2fcc0 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  cated by [sqlite
2fcd0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fce0 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20  ext(C,N)] is.** 
2fcf0 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74           automat
2fd00 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20  ically freed on 
2fd10 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2fd20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fd30 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
2fd40 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2fd50 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b  ize()] for the [
2fd60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fd70 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  nt] containing.*
2fd80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
2fd90 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2fda0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2fdb0 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a  h context C..*/.
2fdc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
2fdd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2fde0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fdf0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
2fe00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fe10 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
2fe20 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d  nctions {H16240}
2fe30 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
2fe40 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
2fe50 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
2fe60 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2fe70 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2fe80 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
2fe90 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
2fea0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
2feb0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
2fec0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2fed0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
2fee0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2fef0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ff00 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
2ff10 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
2ff20 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
2ff30 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2ff40 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
2ff50 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2ff60 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2ff70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2ff80 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2ff90 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
2ffa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ffb0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2ffc0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2ffd0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34  TS:.**.** {H1624
2ffe0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2fff0 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e  user_data(C)] in
30000 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30010 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
30020 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e            P poin
30030 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
30040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30050 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
30060 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
30070 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
30080 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30090 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
300a0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
300b0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
300c0 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
300d0 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
300e0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
300f0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f  ontext] C..*/.vo
30100 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
30110 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
30120 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
30130 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
30140 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
30150 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
30160 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
30170 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
30180 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
30190 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
301a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
301b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
301c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
301d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
301e0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
301f0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
30200 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
30210 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
30220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
30230 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30240 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
30250 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
30260 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
30270 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
30280 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
30290 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
302a0 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65  .** {H16253} The
302b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
302c0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20  t_db_handle(C)] 
302d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
302e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
302f0 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f  **          D po
30300 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
30310 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30320 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
30330 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
30340 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
30350 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30360 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
30370 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
30380 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
30390 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
303a0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
303b0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
303c0 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
303d0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
303e0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
303f0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
30400 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
30410 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
30420 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b  Auxiliary Data {
30430 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e  H16270} <S20200>
30440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
30450 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
30460 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
30470 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
30480 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
30490 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
304a0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
304b0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
304c0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
304d0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
304e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
304f0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
30500 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
30510 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
30520 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
30530 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
30540 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
30550 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
30560 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
30570 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
30580 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
30590 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
305a0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
305b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
305c0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
305d0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
305e0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
305f0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
30600 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30610 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
30620 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
30630 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
30640 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
30650 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
30660 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30670 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
30680 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
30690 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
306a0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
306b0 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
306c0 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
306d0 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
306e0 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
306f0 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
30700 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
30710 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
30720 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
30730 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
30740 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
30750 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
30760 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
30770 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30780 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
30790 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
307a0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
307b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
307c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49  ined function. I
307d0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
307e0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
307f0 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
30800 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
30810 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
30820 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
30830 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
30840 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
30850 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
30860 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
30870 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
30880 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30890 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
308a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
308b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
308c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
308d0 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
308e0 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
308f0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
30900 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
30910 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
30920 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
30930 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
30940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30950 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
30960 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
30970 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
30980 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
30990 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
309a0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
309b0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
309c0 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
309d0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
309e0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
309f0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
30a00 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
30a10 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
30a20 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
30a30 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
30a40 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
30a50 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
30a60 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
30a70 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
30a80 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
30a90 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
30aa0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
30ab0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
30ac0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
30ad0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
30ae0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
30af0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
30b00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
30b10 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
30b20 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20   any time.  The 
30b30 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
30b40 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
30b50 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
30b60 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
30b70 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
30b80 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
30b90 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
30ba0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
30bb0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
30bc0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
30bd0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
30be0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
30bf0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
30c00 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
30c10 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
30c20 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
30c30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30c40 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
30c50 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
30c60 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
30c70 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
30c80 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
30c90 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
30ca0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
30cb0 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  72} The [sqlite3
30cc0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
30cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
30ce0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
30cf0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65  *          to me
30d00 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30d10 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70  d with the Nth p
30d20 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
30d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
30d40 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63           whose c
30d50 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20  ontext is C, or 
30d60 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
30d70 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   no metadata ass
30d80 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
30d90 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61      with that pa
30da0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
30db0 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c  H16274} The [sql
30dc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30dd0 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72  (C,N,P,D)] inter
30de0 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d  face assigns a m
30df0 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
30e00 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f      pointer P to
30e10 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
30e20 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
30e30 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74  nction with cont
30e40 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ext C..**.** {H1
30e50 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c  6276} SQLite wil
30e60 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
30e70 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
30e80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
30e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
30ea0 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61  ch is the metada
30eb0 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c  ta pointer P fol
30ec0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
30ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
30ee0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30ef0 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e  a(C,N,P,D)] when
30f00 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
30f10 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20  o hold.**       
30f20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e     the metadata.
30f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20  .**.** {H16277} 
30f40 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
30f50 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66   hold metadata f
30f60 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  or an SQL functi
30f70 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
30f80 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68           when th
30f90 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
30fa0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
30fb0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38  s..**.** {H16278
30fc0 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
30fd0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
30fe0 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  P,D)] is invoked
30ff0 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  , the destructor
31000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
31010 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70  called for any p
31020 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73  rior metadata as
31030 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
31040 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
31050 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
31060 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65  ext C and parame
31070 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ter N..**.** {H1
31080 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  6279} SQLite wil
31090 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f  l call destructo
310a0 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64  rs for any metad
310b0 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e  ata it is holdin
310c0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
310d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70   a particular [p
310e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
310f0 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72  t] S when either
31100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31110 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31120 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31130 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
31140 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
31150 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
31160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31170 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
31180 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
31190 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
311a0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
311b0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
311c0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
311d0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
311e0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
311f0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
31200 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
31210 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
31220 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
31230 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
31240 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
31250 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
31260 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
31270 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
31280 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
31290 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
312a0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
312b0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
312c0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
312d0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
312e0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
312f0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
31300 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
31310 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
31320 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
31330 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
31340 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
31350 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
31360 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
31370 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
31380 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
31390 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
313a0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
313b0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
313c0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
313d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
313e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
313f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
31400 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
31410 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
31420 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
31430 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
31440 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
31450 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
31460 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
31470 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
31480 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
31490 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
314a0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
314b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
314c0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
314d0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
314e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
314f0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
31500 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
31510 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
31520 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
31530 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
31540 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
31550 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
31560 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
31570 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
31580 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
31590 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
315a0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
315b0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
315c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
315d0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
315e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
315f0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
31600 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
31610 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
31620 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
31630 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
31640 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
31650 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
31660 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
31670 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
31680 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
31690 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
316a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
316b0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
316c0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
316d0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
316e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
316f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
31700 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31710 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
31720 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
31730 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
31740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31750 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31760 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
31770 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
31780 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
31790 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
317a0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
317b0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
317c0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
317d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
317e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
317f0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31800 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
31810 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
31820 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31830 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31840 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
31850 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
31860 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
31870 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
31880 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
31890 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
318a0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
318b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
318c0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
318d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
318e0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
318f0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
31900 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31910 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
31920 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
31930 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
31940 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
31950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31960 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31970 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
31980 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
31990 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
319a0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
319b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
319c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
319d0 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
319e0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
319f0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
31a00 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
31a10 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
31a20 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
31a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31a40 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
31a50 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
31a60 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
31a70 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
31a80 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
31a90 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
31aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31ab0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
31ac0 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
31ad0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
31ae0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
31af0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
31b00 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
31b10 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
31b20 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
31b30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31b40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31b50 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
31b60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31b70 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
31b80 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
31b90 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
31ba0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
31bb0 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
31bc0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
31bd0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
31be0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31bf0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
31c00 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
31c10 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31c20 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
31c30 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
31c40 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
31c50 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
31c60 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
31c70 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
31c80 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
31c90 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
31ca0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31cb0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
31cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31cd0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
31ce0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
31cf0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
31d00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
31d10 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
31d20 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
31d30 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
31d40 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
31d50 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
31d60 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
31d70 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
31d80 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
31d90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31da0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
31db0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
31dc0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
31dd0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
31de0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
31df0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
31e00 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
31e10 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
31e20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
31e30 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
31e40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
31e50 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
31e60 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
31e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31e80 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
31e90 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
31ea0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
31eb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31ec0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
31ed0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
31ee0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
31ef0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
31f00 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
31f10 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
31f20 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
31f30 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
31f40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31f50 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
31f60 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
31f70 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
31f80 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
31f90 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
31fa0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
31fb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
31fc0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
31fd0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31fe0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
31ff0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
32000 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32010 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
32020 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
32030 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
32040 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
32050 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
32060 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32070 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
32080 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
32090 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
320a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
320b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
320c0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
320d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
320e0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
320f0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
32100 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
32110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
32120 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
32130 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
32140 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
32150 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32160 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32170 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
32180 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32190 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
321a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
321b0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
321c0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
321d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
321e0 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
321f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
32200 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32210 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32230 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
32240 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
32250 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
32260 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
32270 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
32280 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
32290 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
322a0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
322b0 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
322c0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
322d0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
322e0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
322f0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
32300 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32310 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
32320 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32330 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
32340 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
32350 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
32360 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32370 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
32380 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
32390 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
323a0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
323b0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
323c0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
323d0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
323e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
323f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32410 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
32420 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
32430 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
32440 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
32450 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
32460 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
32470 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
32480 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
32490 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
324a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
324b0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
324c0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
324d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
324e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
324f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32500 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32510 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
32520 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
32530 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
32540 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
32550 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
32560 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
32570 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
32580 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
32590 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
325a0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
325b0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
325c0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
325d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
325e0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
325f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32600 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
32610 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
32620 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
32630 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
32640 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
32650 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
32660 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
32670 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
32680 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
32690 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
326a0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
326b0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
326c0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
326d0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
326e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
326f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32700 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
32710 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
32720 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
32730 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
32740 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
32750 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
32760 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
32770 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
32780 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
32790 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
327a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
327b0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
327c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
327d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
327e0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
327f0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
32800 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
32810 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32820 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
32830 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
32840 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32850 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
32860 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
32870 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
32880 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32890 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
328a0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
328b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
328c0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
328d0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
328e0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
328f0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
32900 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
32910 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
32920 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
32930 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
32940 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
32950 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
32960 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32970 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
32980 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
32990 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
329a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
329b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
329c0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
329d0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
329e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
329f0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
32a00 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
32a10 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
32a20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32a30 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
32a40 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
32a50 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
32a60 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
32a70 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
32a80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32a90 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
32aa0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
32ab0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
32ac0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
32ad0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
32ae0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32af0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33  S:.**.** {H16403
32b00 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65  } The default re
32b10 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
32b20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  any SQL function
32b30 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
32b40 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71  {H16406} The [sq
32b50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32b60 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  b(C,V,N,D)] inte
32b70 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32b80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
32b90 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
32ba0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
32bb0 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20   BLOB that is N 
32bc0 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
32bd0 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20    in length and 
32be0 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69  with content poi
32bf0 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a  nted to by V..**
32c00 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65  .** {H16409} The
32c10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32c20 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e  _double(C,V)] in
32c30 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32c40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32c50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32c60 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32c70 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
32c80 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  int value V..**.
32c90 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20  ** {H16412} The 
32ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32cb0 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e  error(C,V,N)] in
32cc0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32cd0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
32ce0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
32cf0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32d00 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
32d10 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
32d20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
32d30 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
32d40 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61  TF-8 error messa
32d50 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56  ge copied from V
32d60 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20   up to the.**   
32d70 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72         first zer
32d80 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20  o byte or until 
32d90 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
32da0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
32db0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35  e..**.** {H16415
32dc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32dd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c  esult_error16(C,
32de0 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
32df0 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
32e00 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
32e10 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32e20 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
32e30 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
32e40 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
32e50 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
32e60 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61   and a UTF-16 na
32e70 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
32e80 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
32e90 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
32ea0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
32eb0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
32ec0 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
32ed0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
32ee0 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
32ef0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
32f00 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54  **.** {H16418} T
32f10 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32f20 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
32f30 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
32f40 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
32f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
32f60 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
32f70 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
32f80 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
32f90 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
32fa0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
32fb0 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
32fc0 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
32fd0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
32fe0 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
32ff0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
33000 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
33010 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
33020 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
33030 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
33040 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
33050 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
33060 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
33070 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
33080 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
33090 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
330a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
330b0 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {H16424} The [sq
330c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
330d0 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
330e0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
330f0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
33100 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
33110 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
33120 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
33130 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
33140 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
33150 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
33160 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
33170 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nged..**.** {H16
33180 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
33190 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
331a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
331b0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
331c0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
331d0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
331e0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
331f0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
33200 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d  ..**.** {H16430}
33210 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
33220 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
33230 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
33240 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
33250 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
33260 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
33270 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
33280 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
33290 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54  **.** {H16433} T
332a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
332b0 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
332c0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
332d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
332e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
332f0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
33300 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
33310 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
33320 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
33330 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
33340 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
33350 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
33360 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
33370 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
33380 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  F-8 string.**   
33390 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
333a0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
333b0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
333c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
333d0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
333e0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
333f0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
33400 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {H16439} The [s
33410 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33420 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
33430 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
33440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33450 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
33460 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
33470 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74  e the UTF-16 nat
33480 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
33490 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
334a0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
334b0 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
334c0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
334d0 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
334e0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
334f0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
33500 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
33510 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  442} The [sqlite
33520 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
33530 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
33540 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
33550 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
33560 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
33570 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
33580 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  he UTF-16 big-en
33590 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
335a0 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
335b0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
335c0 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
335d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
335e0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
335f0 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
33600 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
33610 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b  * {H16445} The [
33620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33630 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
33640 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
33650 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
33660 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
33670 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
33680 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
33690 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
336a0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
336b0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
336c0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
336d0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
336e0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
336f0 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
33700 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
33710 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
33720 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
33730 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
33740 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
33750 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
33760 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
33770 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
33780 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72   to be the [unpr
33790 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
337a0 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
337b0 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
337c0 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20  ** {H16451} The 
337d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
337e0 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
337f0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
33800 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33810 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
33820 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
33830 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42  e an N-byte BLOB
33840 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
33850 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68  *.** {H16454} Th
33860 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
33870 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
33880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33890 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
338a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
338b0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
338c0 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
338d0 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
338e0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
338f0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
33900 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {H16457} If the 
33910 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
33920 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
33930 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
33940 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
33950 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33960 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
33970 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
33980 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
33990 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
339a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
339b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
339c0 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
339d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
339e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
339f0 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
33a00 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
33a10 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
33a20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
33a30 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
33a40 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
33a50 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
33a60 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
33a70 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
33a80 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
33a90 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74  ** {H16460} If t
33aa0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
33ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
33ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33ad0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
33ae0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33af0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
33b00 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
33b10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
33b20 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
33b30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33b40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
33b50 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
33b60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
33b70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33b80 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
33b90 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
33ba0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
33bb0 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
33bc0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
33bd0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
33be0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33bf0 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
33c00 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
33c10 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33  y..**.** {H16463
33c20 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
33c30 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
33c40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
33c50 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
33c60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
33c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33c80 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
33c90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33ca0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
33cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33cd0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
33ce0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
33cf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33d00 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
33d10 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
33d20 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
33d30 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
33d40 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
33d50 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
33d60 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
33d70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
33d80 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
33d90 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
33da0 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
33db0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
33dc0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
33dd0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
33de0 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
33df0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
33e00 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
33e10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33e20 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33e30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33e40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33e50 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
33e60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
33e70 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
33e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33e90 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
33ea0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
33eb0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33ec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33ed0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
33ee0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33ef0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33f10 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
33f20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
33f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f40 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
33f50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
33f60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33f70 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
33f80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33f90 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33fa0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
33fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33fc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33fd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
33fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33ff0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
34000 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34010 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
34020 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
34030 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34040 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
34050 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
34060 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
34070 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34090 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
340a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
340b0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
340c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
340d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
340e0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
340f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34100 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
34110 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34120 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34130 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34140 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34150 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34160 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
34170 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34180 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
34190 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
341a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
341b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
341c0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
341d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
341e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
341f0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
34200 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
34210 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
34220 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
34230 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
34240 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
34250 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34260 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
34270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34280 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
34290 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
342a0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
342b0 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
342c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
342d0 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
342e0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
342f0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
34300 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
34310 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
34320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34330 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
34340 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
34350 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34360 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
34370 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
34380 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
34390 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
343a0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
343b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
343c0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
343d0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
343e0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
343f0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
34400 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
34410 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
34420 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
34430 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
34440 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
34450 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
34460 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
34470 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
34480 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
34490 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c  6 little-endian,
344a0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
344b0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
344c0 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
344d0 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
344e0 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
344f0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
34500 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
34510 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
34520 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
34530 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
34540 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
34550 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
34560 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
34570 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
34580 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
34590 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
345a0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
345b0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
345c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
345d0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
345e0 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
345f0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
34600 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
34610 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
34620 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
34630 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
34640 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
34650 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
34660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
34670 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
34680 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
34690 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
346a0 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
346b0 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
346c0 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
346d0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
346e0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
346f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34700 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
34710 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34720 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
34730 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
34740 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
34750 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
34760 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
34770 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
34780 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
34790 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
347a0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
347b0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
347c0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
347d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
347e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
347f0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
34800 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
34810 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
34820 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
34830 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
34840 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
34850 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
34860 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
34870 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
34880 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
34890 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
348a0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
348b0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
348c0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
348d0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
348e0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
348f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34900 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
34910 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
34920 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34930 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
34940 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
34950 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
34960 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
34970 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
34980 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
34990 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
349a0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
349b0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
349c0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
349d0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
349e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
349f0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
34a00 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
34a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34a20 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
34a30 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
34a40 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
34a50 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
34a60 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
34a70 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
34a80 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
34a90 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
34aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34ab0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
34ac0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
34ad0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
34ae0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
34af0 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20  *.** {H16603} A 
34b00 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
34b10 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
34b20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
34b30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34b40 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
34b50 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
34b60 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
34b70 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
34b80 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
34b90 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
34ba0 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
34bb0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
34bc0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34bd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
34be0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
34bf0 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
34c00 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
34c10 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {H16604} SQLite 
34c20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
34c30 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
34c40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
34c50 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34c60 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
34c70 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
34c80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
34c90 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
34ca0 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
34cb0 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
34cc0 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
34cd0 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
34ce0 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
34cf0 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
34d00 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
34d10 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 73   {H16606} Succes
34d20 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
34d30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34d40 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
34d50 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
34d60 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
34d70 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
34d80 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
34d90 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
34da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
34db0 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
34dc0 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74  ** {H16609} If t
34dd0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
34de0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
34df0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34e00 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
34e10 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
34e20 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
34e30 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
34e40 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
34e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
34e60 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34e70 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
34e80 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  Lite..**.** {H16
34e90 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
34ea0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
34eb0 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
34ec0 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
34ed0 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {H16615} A col
34ee0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34ef0 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
34f00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
34f10 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
34f20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
34f30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
34f40 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  se()]..**.** {H1
34f50 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
34f60 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
34f70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34f80 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
34f90 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
34fa0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
34fb0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
34fc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
34fd0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
34fe0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
34ff0 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
35000 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
35010 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  f F..**.** {H166
35020 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
35030 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35040 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
35050 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
35060 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
35070 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
35080 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35090 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
350a0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
350b0 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
350c0 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
350d0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
350e0 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {H16624} Foll
350f0 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
35100 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35110 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
35120 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35130 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
35140 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
35150 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
35160 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
35170 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
35180 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  ions on the [dat
35190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
351a0 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
351b0 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
351c0 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
351d0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
351e0 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48  amed X..**.** {H
351f0 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
35200 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35210 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
35220 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
35230 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
35240 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35250 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
35260 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
35270 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
35280 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
35290 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
352a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
352b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
352c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
352d0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
352e0 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68  *.** {H16630} Wh
352f0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
35300 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
35310 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
35320 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
35330 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
35340 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
35350 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
35360 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
35370 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
35380 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
35390 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
353a0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
353b0 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
353c0 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
353d0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
353e0 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
353f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35400 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
35410 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
35420 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
35430 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
35440 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
35450 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35460 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35470 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
35480 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
35490 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
354a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
354b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
354c0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
354d0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
354e0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
354f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35500 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35510 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
35520 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
35530 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35540 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
35550 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
35560 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
35570 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
35580 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
35590 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
355a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
355b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
355c0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
355d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
355e0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
355f0 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
35600 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
35610 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
35620 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
35630 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35640 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
35650 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
35660 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
35670 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
35680 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
35690 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
356a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
356b0 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
356c0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
356d0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
356e0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
356f0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
35700 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
35710 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
35720 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
35730 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
35740 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
35750 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
35760 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
35770 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
35780 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
35790 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
357a0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
357b0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
357c0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
357d0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
357e0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
357f0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
35800 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
35810 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
35820 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
35830 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
35840 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
35850 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
35860 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
35870 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
35880 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
35890 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
358a0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
358b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
358c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
358d0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
358e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
358f0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
35900 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
35910 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
35920 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
35930 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
35940 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
35950 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
35960 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35970 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
35980 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
35990 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
359a0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
359b0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
359c0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
359d0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
359e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
359f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
35a00 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
35a10 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
35a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
35a30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
35a40 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
35a50 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
35a60 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
35a70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35a80 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
35a90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35aa0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
35ab0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35ac0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
35ad0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35ae0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32  S:.**.** {H16702
35af0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
35b00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35b10 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35b20 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
35b30 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
35b40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35b50 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
35b60 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
35b70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35b80 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
35b90 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
35ba0 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
35bb0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
35bc0 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
35bd0 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
35be0 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
35bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
35c00 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
35c10 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
35c20 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
35c30 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68  ** {H16704} Each
35c40 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
35c50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
35c60 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
35c70 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35c90 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
35ca0 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
35cb0 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
35cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
35cd0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
35ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
35cf0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
35d00 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
35d10 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
35d20 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68  *.** {H16706} Th
35d30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
35d40 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
35d50 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
35d60 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
35d70 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
35d80 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
35d90 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
35da0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
35db0 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
35dc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
35dd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35de0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
35df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
35e00 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
35e10 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
35e20 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
35e30 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
35e40 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
35e50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35e60 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
35e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
35e80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
35e90 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
35ea0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
35eb0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
35ec0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
35ed0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
35ee0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35ef0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
35f00 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
35f10 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
35f20 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
35f30 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
35f40 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
35f50 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
35f60 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
35f70 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
35f80 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
35f90 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
35fa0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
35fb0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
35fc0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
35fd0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
35fe0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
35ff0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36000 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
36010 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36020 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
36030 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36040 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36050 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36060 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
36070 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
36080 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
36090 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
360a0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
360b0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
360c0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
360d0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
360e0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
360f0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
36100 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
36110 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
36120 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
36130 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
36140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
36150 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
36160 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
36170 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
36180 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
36190 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
361a0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
361b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
361c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
361d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
361e0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
361f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36200 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36210 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
36220 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
36230 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
36240 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
36250 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
36260 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
36270 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
36280 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
36290 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
362a0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
362b0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
362c0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
362d0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
362e0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
362f0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
36300 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
36310 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
36320 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
36330 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
36340 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
36350 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
36360 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
36370 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
36380 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
36390 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
363a0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
363b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
363c0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
363d0 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
363e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
363f0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
36400 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
36410 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
36420 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
36430 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
36440 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
36450 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
36460 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
36470 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36480 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d  :.**.** {H10533}
36490 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
364a0 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
364b0 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
364c0 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
364d0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
364e0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
364f0 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
36500 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
36510 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
36520 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
36530 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
36540 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
36550 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
36560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d  ..**.** {H10536}
36570 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
36580 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
36590 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
365a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
365b0 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
365c0 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
365d0 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
365e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
365f0 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
36600 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
36610 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
36620 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
36630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
36640 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
36650 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
36660 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36670 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36680 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53  iles {H10310} <S
36690 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  20000>.**.** If 
366a0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
366b0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
366c0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
366d0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
366e0 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
366f0 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
36700 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
36710 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
36720 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
36730 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
36740 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
36750 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
36760 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36780 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36790 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
367a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
367b0 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
367c0 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
367d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
367e0 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73  e to modify this
367f0 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61   variable once a
36800 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36810 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65  ction].** has be
36820 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
36830 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
36840 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
36850 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
36860 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
36870 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
36880 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
36890 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
368a0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
368b0 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
368c0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
368d0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
368e0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
368f0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
36900 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
36910 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
36920 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
36930 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53  Mode {H12930} <S
36940 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  60200>.** KEYWOR
36950 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
36960 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  mode}.**.** The 
36970 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
36980 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
36990 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
369a0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
369b0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
369c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
369d0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
369e0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
369f0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
36a00 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  .  Autocommit mo
36a10 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
36a20 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ult..** Autocomm
36a30 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
36a40 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
36a50 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41   statement..** A
36a60 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36a70 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
36a80 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
36a90 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
36aa0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
36ab0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
36ac0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
36ad0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
36ae0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
36af0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
36b00 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
36b10 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
36b20 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
36b30 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
36b40 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
36b50 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
36b60 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
36b70 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
36b80 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
36b90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
36ba0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
36bb0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
36bc0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
36bd0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
36be0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
36bf0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
36c00 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
36c10 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
36c20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36c30 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d  :.**.** {H12931}
36c40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
36c50 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d  t_autocommit(D)]
36c60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36c70 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
36c80 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
36c90 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  if the [database
36ca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69   connection] D i
36cb0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
36cc0 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20  utocommit.**    
36cd0 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70        mode, resp
36ce0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
36cf0 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d  {H12932} Autocom
36d00 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
36d10 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
36d20 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f   {H12933} Autoco
36d30 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
36d40 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65  abled by a succe
36d50 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74  ssful [BEGIN] st
36d60 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  atement..**.** {
36d70 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d  H12934} Autocomm
36d80 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  it mode is enabl
36d90 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
36da0 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b  ul [COMMIT] or [
36db0 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20  ROLLBACK].**    
36dc0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e        statement.
36dd0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
36de0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33  NS:.**.** {A1293
36df0 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  6} If another th
36e00 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
36e10 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
36e20 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
36e30 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  se.**          c
36e40 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
36e50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
36e60 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
36e70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36e80 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
36e90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
36ea0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
36eb0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
36ec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36ed0 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
36ee0 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
36ef0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
36f00 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36  ent {H13120} <S6
36f10 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0600>.**.** The 
36f20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
36f30 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
36f40 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
36f50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
36f60 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
36f70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
36f80 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
36f90 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68    The database h
36fa0 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62  andle returned b
36fb0 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  y.** sqlite3_db_
36fc0 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61  handle is the sa
36fd0 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
36fe0 6c 65 20 74 68 61 74 20 77 61 73 20 74 68 65 20  le that was the 
36ff0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
37000 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
37010 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
37020 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
37030 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
37040 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
37050 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
37060 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
37070 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ce..**.** INVARI
37080 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
37090 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  123} The [sqlite
370a0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20  3_db_handle(S)] 
370b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
370c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
370d0 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b          to the [
370e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
370f0 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20  ion] associated 
37100 77 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20  with the.**     
37110 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
37120 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
37130 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
37140 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
37150 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
37160 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
37170 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
37180 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed statement {H1
37190 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a  3140} <S60600>.*
371a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
371b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
371c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
371d0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
371e0 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
371f0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
37200 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37220 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69  pDb.  If pStmt i
37230 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
37240 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
37250 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
37260 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
37270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37280 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
37290 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
372a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
372b0 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20   If no prepared 
372c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
372d0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
372e0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
372f0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
37300 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  s NULL..**.** IN
37310 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37320 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20 69 73  {H13143} If D is
37330 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
37340 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f  nection] that ho
37350 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  lds one or more.
37360 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 69  **          unfi
37370 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65  nalized [prepare
37380 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e  d statements] an
37390 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d S is a NULL po
373a0 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  inter,.**       
373b0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
373c0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
373d0 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
373e0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
373f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
37400 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70 61  one of the prepa
37410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
37420 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 44  ssociated with D
37430 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d  ..**.** {H13146}
37440 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61   If D is a [data
37450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37460 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75   that holds no u
37470 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20  nfinalized.**   
37480 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
37490 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64   statements] and
374a0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
374b0 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  nter, then.**   
374c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
374d0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
374e0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
374f0 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
37500 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nter..**.** {H13
37510 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b  149} If S is a [
37520 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37530 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61  nt] in the [data
37540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37550 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   D.**          a
37560 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20  nd S is not the 
37570 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
37580 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68  atement in D, th
37590 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
375a0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
375b0 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65  t(D, S)] routine
375c0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20   shall return a 
375d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
375e0 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20      to the next 
375f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37600 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e  nt in D after S.
37610 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20  .**.** {H13152} 
37620 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 74  If S is the last
37630 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37640 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20  ment] in the.** 
37650 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
37660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37670 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
37680 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
37690 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
376a0 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
376b0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
376c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ter..**.** ASSUM
376d0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
376e0 31 33 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61  13154} The [data
376f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37700 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
37710 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  call to.**      
37720 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78      [sqlite3_nex
37730 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
37740 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
37750 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  en database.**  
37760 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69          connecti
37770 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
37780 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
37790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
377a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
377b0 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
377c0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
377d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
377e0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
377f0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
37800 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
37810 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
37820 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36  cks {H12950} <S6
37830 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
37840 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37850 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37860 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37870 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
37880 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37890 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
378a0 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
378b0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
378c0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
378d0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
378e0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
378f0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
37900 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37910 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37920 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
37930 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37940 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37950 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37960 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
37970 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37980 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
37990 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
379a0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
379b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
379c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
379d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
379e0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
379f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37a00 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37a10 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41  idden..** The pA
37a20 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
37a30 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
37a40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
37a50 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
37a60 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
37a70 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
37a80 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
37a90 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
37aa0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
37ab0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
37ac0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
37ad0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
37ae0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
37af0 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20  ed, its.** pArg 
37b00 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
37b10 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
37b20 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
37b30 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
37b40 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
37b50 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
37b60 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
37b70 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
37b80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37b90 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
37ba0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
37bb0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
37bc0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
37bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37be0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
37bf0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
37c00 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
37c10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
37c20 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
37c30 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
37c40 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
37c50 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
37c60 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
37c70 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
37c80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
37c90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
37ca0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
37cb0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
37cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
37cd0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
37ce0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
37cf0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
37d00 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
37d10 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
37d20 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
37d30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46  allback..**.** F
37d40 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
37d50 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
37d60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
37d70 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
37d80 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
37d90 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
37da0 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
37db0 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
37dc0 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
37dd0 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
37de0 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
37df0 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
37e00 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  r..** The rollba
37e10 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
37e20 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
37e30 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
37e40 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
37e50 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
37e60 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
37e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
37e80 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f  losed..** The ro
37e90 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
37ea0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
37eb0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
37ec0 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
37ed0 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
37ee0 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
37ef0 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
37f00 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f  * <todo> Check o
37f10 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a  n this </todo>.*
37f20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
37f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20  .**.** {H12951} 
37f40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
37f50 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
37f60 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
37f70 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
37f80 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
37f90 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
37fa0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
37fb0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
37fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
37fd0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
37fe0 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s on the [databa
37ff0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
38000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d  ..**.** {H12952}
38010 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
38020 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
38030 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
38040 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
38050 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  nt.**          f
38060 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
38070 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
38080 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
38090 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
380a0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
380b0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
380c0 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ll for a particu
380d0 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  lar database con
380e0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
380f0 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68 20 63   {H12953} Each c
38100 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
38110 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f  commit_hook()] o
38120 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
38130 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
38140 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
38150 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
38160 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20  .** {H12954} If 
38170 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
38180 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
38190 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
381a0 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
381b0 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d     then the comm
381c0 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
381d0 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
381e0 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
381f0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
38200 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
38210 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a  action commits..
38220 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49  **.** {H12955} I
38230 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c  f the commit cal
38240 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
38250 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  n-zero then the 
38260 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20  commit is.**    
38270 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20        converted 
38280 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
38290 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20  .**.** {H12961} 
382a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
382b0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
382c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
382d0 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
382e0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
382f0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
38300 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
38310 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
38320 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
38330 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
38340 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64  s back on the [d
38350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38360 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
38370 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
38380 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
38390 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
383a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
383b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
383c0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
383d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
383e0 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  h the same.**   
383f0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
38400 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
38410 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
38420 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  irst call.**    
38430 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74        for a part
38440 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  icular database 
38450 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
38460 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63  .** {H12963} Eac
38470 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
38480 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
38490 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
384a0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
384b0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
384c0 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
384d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34  s..**.** {H12964
384e0 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
384f0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
38500 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
38510 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
38520 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
38530 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
38540 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
38550 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
38560 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
38570 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
38580 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
38590 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76  rolls back..*/.v
385a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
385b0 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
385c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
385d0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
385e0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
385f0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
38600 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
38610 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
38620 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
38630 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
38640 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
38650 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2970} <S60400>.*
38660 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38670 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
38680 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
38690 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
386a0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
386b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
386c0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
386d0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
386e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
386f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
38700 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
38710 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
38720 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
38730 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
38740 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
38750 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
38760 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
38770 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
38780 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
38790 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
387a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
387b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
387c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
387d0 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
387e0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
387f0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
38800 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eted..** The fir
38810 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
38820 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
38830 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
38840 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
38850 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
38860 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
38870 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
38880 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
38890 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
388a0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
388b0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
388c0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
388d0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the op