/ Hex Artifact Content
Login

Artifact 157cd9932c2747a6ef3cb091e006185f4f9105d3:


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 33 38 37 20 32 30 30 38 2f 30  n,v 1.387 2008/0
05f0: 38 2f 30 35 20 31 37 3a 35 33 3a 32 33 20 64 72  8/05 17:53:23 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 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 20  umbers {H10010} 
0840: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60100>.**.** T
0850: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0860: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52  N and SQLITE_VER
0870: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66  SION_NUMBER #def
0880: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73  ines in.** the s
0890: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70  qlite3.h file sp
08a0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f  ecify the versio
08b0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68  n of SQLite with
08c0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68   which.** that h
08d0: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
08e0: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
08f0: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66  The "version" of
0900: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72   SQLite is a str
0910: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
0920: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20  "X.Y.Z"..** The 
0930: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f  phrase "alpha" o
0940: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62  r "beta" might b
0950: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72  e appended after
0960: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58   the Z..** The X
0970: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20   value is major 
0980: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0990: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74  lways 3 in SQLit
09a0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c  e3..** The X val
09b0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
09c0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63  when backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73   break backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
0a20: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69  ** The Y value i
0a30: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
0a40: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f  ion number and o
0a50: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0a60: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0a70: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0a80: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0a90: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0aa0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0ab0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0ac0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20  tible..** The Z 
0ad0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c  value is the rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20  ease number and 
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0b00: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0b10: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0b20: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65  ack to 0 wheneve
0b30: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  r Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
0b50: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0b60: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0b70: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0b80: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a  on_number()]..**
0b90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
0ba0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54  **.** {H10011} T
0bb0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0bc0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65  N #define in the
0bd0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0be0: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20  r file shall.** 
0bf0: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74           evaluat
0c00: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  e to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  iated..**.** {H1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0c90: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65  #define shall re
0ca0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65  solve to an inte
0cb0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
0cc0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
0cd0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
0ce0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
0cf0: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20   Y, and Z.**    
0d00: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61        are the ma
0d10: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e  jor version, min
0d20: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20  or version, and 
0d30: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a  release number..
0d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
0d60: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
0d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0d80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45  ION_NUMBER  --VE
0d90: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a  RSION-NUMBER--..
0da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0db0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
0dc0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
0dd0: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30   {H10020} <S6010
0de0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
0df0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
0e00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
0e10: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
0e20: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0e30: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
0e40: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
0e50: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e60: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
0e70: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
0e80: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
0e90: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
0ea0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
0eb0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
0ec0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
0ed0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
0ee0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
0ef0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
0f00: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
0f10: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65  y that.** sqlite
0f20: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
0f30: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74  ber() always ret
0f40: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
0f50: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
0f60: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a  N_NUMBER]..**.**
0f70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
0f80: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
0f90: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
0fa0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
0fb0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
0fc0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0fd0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fe0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0ff0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1000: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1010: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1020: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1030: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
1040: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
1050: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1060: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  the DLL..**.** I
1070: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1080: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73   {H10021} The [s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
10a0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65  n_number()] inte
10b0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
10c0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
10d0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
10e0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
10f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a  ON_NUMBER]..**.*
1100: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b  * {H10022} The [
1110: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
1120: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1130: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a   shall contain.*
1140: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1150: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
1170: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  ng..**.** {H1002
1180: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1190: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
11a0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
11b0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
11c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11d0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11e0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11f0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
1200: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
1210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1220: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1240: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1260: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1280: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1290: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
12a0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d  eadsafe {H10100}
12b0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60100>.**.** 
12c0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
12d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
12e0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
12f0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1300: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1310: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1320: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1330: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1340: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1350: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1360: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
1370: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
1380: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1390: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
13a0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
13b0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
13c0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
13d0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
13e0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13f0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1400: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1410: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1420: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1430: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1440: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1450: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1460: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1470: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1480: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1490: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
14a0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
14b0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
14c0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
14d0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
14e0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1500: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1510: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
1520: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1530: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1540: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1550: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1560: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1570: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1580: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15a0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
15b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
15c0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
15d0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
15e0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
15f0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
1600: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1610: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
1620: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
1630: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
1640: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20  READSAFE=1 then 
1650: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
1660: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
1670: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
1680: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
1690: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
16a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
16c0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
16d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16e0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1700: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
1710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1720: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72  TEX].  The retur
1730: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1740: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a  function shows.*
1750: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75  * only the defau
1760: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  lt compile-time 
1770: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79  setting, not any
1780: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
1790: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74  s.** to that set
17a0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ting..**.** INVA
17b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17c0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
17d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
17e0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
17f0: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20   return nonzero 
1800: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1810: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1820: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1830: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1840: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  by default.**   
1850: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69         or zero i
1860: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1870: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20  piled such that 
1880: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20  mutexes are.**  
1890: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e          permanen
18a0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  tly disabled..**
18b0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
18c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18d0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
18e0: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
18f0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1900: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61     shall not cha
1910: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73  nge when mutex s
1920: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66  etting are modif
1930: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20  ied at.**       
1940: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67     runtime using
1950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
1970: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  e and .**       
1980: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68     especially th
1990: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
19a0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a  _SINGLETHREAD],.
19b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
19d0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
19f0: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ED],.**         
1a00: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
1a10: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73  FIG_MUTEX] verbs
1a20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a30: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1a40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a50: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1a60: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1a70: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1a80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1ab0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1ac0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1ad0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ae0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1af0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1b00: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1b10: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1b20: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1b30: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1b40: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1b50: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1b60: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1b70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1b80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1b90: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1bb0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1bc0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1bd0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1be0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1bf0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1c00: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1c10: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1c20: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1c30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1c50: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1c60: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c80: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1c90: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1ca0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1cb0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1cc0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1cd0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ce0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1cf0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1d00: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1d10: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1d20: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1d30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d40: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1d50: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1d60: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1d70: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1d80: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1d90: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1da0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1db0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1dc0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1dd0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1de0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1df0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1e00: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1e10: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1e20: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1e30: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1e40: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1e50: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1e60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1e70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1e80: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nly..**.** INVAR
1e90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ea0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
1eb0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
1ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
1ed0: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1ee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1ef0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ger..**.** {H102
1f10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1f20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1f30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1f40: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1f60: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f70: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66  teger..*/.#ifdef
1f80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1f90: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
1fa0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1fb0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1fc0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1fd0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1fe0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
1ff0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2000: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2010: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2020: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2030: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2040: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2050: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2060: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2070: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2080: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2090: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
20a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
20b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
20c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
20d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
20e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
20f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2100: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2110: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2120: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2130: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2140: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2150: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2160: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2170: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2180: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2190: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
21a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
21b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
21c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
21d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
21e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
21f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2200: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30  on {H12010} <S30
2210: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  100><S40200>.**.
2220: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2230: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
2240: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
2250: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  e3] object..**.*
2260: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2270: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2280: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2290: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
22a0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
22b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
22c0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
22d0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
22e0: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  les] associated 
22f0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  with.** the [sql
2300: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2310: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2320: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2330: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ject..** The [sq
2340: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2360: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61   be used to loca
2370: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61  te all.** [prepa
2380: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2390: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23b0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72  ection] if desir
23c0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63  ed..** Typical c
23d0: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c  ode might look l
23e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
23f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2400: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  >.** sqlite3_stm
2410: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69  t *pStmt;.** whi
2420: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c  le( (pStmt = sql
2430: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64  ite3_next_stmt(d
2440: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20  b, 0))!=0 ){.** 
2450: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33  &nbsp;   sqlite3
2460: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
2470: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e  ;.** }.** </pre>
2480: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2490: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
24a0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
24b0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
24c0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
24d0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
24e0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
24f0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2500: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2510: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  TS:.**.** {H1201
2520: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
2530: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2540: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2550: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
2560: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
2570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2580: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  bject C..**.** {
2590: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73  H12012} A succes
25a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
25c0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c  shall return SQL
25d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
25e0: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73  12013} A success
25f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2600: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2610: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c  hall release all
2620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2630: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72  ory and system r
2640: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
2650: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
2660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2670: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a  *          C..**
2680: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63  .** {H12014} A c
2690: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26a0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b  close(C)] on a [
26b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20  ion] C that.**  
26d0: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20          has one 
26e0: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72  or more open [pr
26f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2700: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  s] shall fail wi
2710: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2720: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2730: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  error code..**.*
2740: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c  * {H12015} A cal
2750: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2760: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20  ose(C)] where C 
2770: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2780: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  r shall.**      
2790: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54      return SQLIT
27a0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
27b0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  019} When [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20  e3_close(C)] is 
27d0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61  invoked on a [da
27e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27f0: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] C.**         
2800: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64   that has a pend
2810: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  ing transaction,
2820: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2830: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2840: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63        rolled bac
2850: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  k..**.** ASSUMPT
2860: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
2870: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d  016} The C param
2880: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2890: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20  _close(C)] must 
28a0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
28b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
28c0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
28d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28e0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28f0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
2900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2910: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2920: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
2940: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
2950: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
2960: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2a90: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2aa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ab0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2ac0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2ad0: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2ae0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2af0: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
2b00: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
2b10: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
2b20: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
2b30: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
2b40: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2b50: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2b60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2b80: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2b90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2ba0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2bb0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2bc0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2bd0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2be0: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2bf0: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2c00: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2c10: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2c20: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2c30: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2c40: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2c50: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2c60: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2c70: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2c80: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2c90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2ca0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2cb0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2cc0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2cd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2ce0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2cf0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2d00: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2d10: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2d20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d30: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2d40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2d50: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2d60: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2d70: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2d80: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2d90: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2da0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2db0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2dc0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2dd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2de0: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2df0: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2e00: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2e10: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2e20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2e30: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2e40: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2e50: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2e60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2e70: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2e80: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2e90: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2ea0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2eb0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2ec0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2ed0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2ee0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2ef0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2f00: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2f10: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2f20: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2f40: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2f70: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2f80: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2f90: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2fa0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fb0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2fc0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2fd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2ff0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
3000: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  101} A successfu
3010: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
3020: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3030: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20  S,C,A,E)].**    
3040: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75        shall sequ
3050: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74  entially evaluat
3060: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
3070: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20  -8 encoded,.**  
3080: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
3090: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
30a0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
30b0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
30c0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  d.**          st
30d0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
30e0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
30f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3100: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
3110: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {H12102} If the 
3120: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3130: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3140: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
3150: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3160: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
3170: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
3180: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
3190: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
31a0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
31b0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
31c0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
31d0: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  H12104} The retu
31e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
3200: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
3210: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
3220: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
3230: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
3240: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
3250: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  letion..**.** {H
3260: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
3270: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
3280: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3290: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
32a0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
32b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
32c0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
32d0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
32e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d  ..**.** {H12107}
32f0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
3300: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
3310: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
3320: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3330: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
3340: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
3350: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3360: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3370: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
3380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3390: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
33a0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
33b0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
33c0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
33d0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33e0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
33f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66  *.** {H12110} If
3400: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3410: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3420: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3440: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3450: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3460: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3470: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3480: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3490: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
34a0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
34b0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
34c0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34d0: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65  .** {H12113} The
34e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
34f0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3500: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3510: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3520: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3530: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3540: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3550: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20  .**.** {H12116} 
3560: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3570: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3580: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70  ll set the 2nd p
3590: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
35b0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
35c0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
35d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
35e0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
35f0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
3600: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {H12119} The [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3620: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3630: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3640: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3650: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3660: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
3670: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3680: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
3690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
36a0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
36b0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
36c0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
36d0: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
36e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3700: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ext()]..**.** {H
3710: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3730: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3740: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3750: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3760: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3770: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3780: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3790: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
37a0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
37b0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
37c0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
37e0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
37f0: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68  * {H12125} If th
3800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3810: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3820: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3850: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  all silently dis
3860: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c  card query resul
3870: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  ts..**.** {H1213
3880: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3890: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
38a0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
38b0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
38c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
38d0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53  tements in the S
38e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
38f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3900: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3910: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3920: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3930: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3950: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3960: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3970: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3980: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
39a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
39b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
39c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
39d0: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {H12134} The [s
39e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
39f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3a00: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3a10: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3a20: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3a30: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3a40: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3a50: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  errors..**.** {H
3a60: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3a70: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3a80: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3a90: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
3aa0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
3ab0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
3ac0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3ae0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3af0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3b10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66  *.** {H12138} If
3b30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3b40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3b50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3b60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3b70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3b80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3b90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
3ba0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
3bb0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
3bc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
3bd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
3be0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
3bf0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3c00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3c10: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3c20: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3c30: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3c40: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3c50: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3c60: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  rors..**.** ASSU
3c70: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
3c80: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  A12141} The firs
3c90: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3cb0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
3cc0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
3cd0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
3ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
3cf0: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20  ** {A12142} The 
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3d10: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
3d20: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
3d30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3d40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3d50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ning..**.** {A12
3d60: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3d70: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
3d80: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
3d90: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
3da0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
3db0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
3dc0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
3dd0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
3de0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
3df0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3e00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3e10: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65  .** {A12145} The
3e20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3e30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3e40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3e50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3e60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3e70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
3e80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
3e90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3ea0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3eb0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3ec0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3ef0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3f00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3f30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3f40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3f50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3f60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3f70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3f80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3fc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3fd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3fe0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4010: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4020: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4030: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4040: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10210} <S10700>.
4050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4060: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4070: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
4080: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4090: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
40a0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
40b0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
40c0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
40d0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
40e0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
40f0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4100: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4110: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4120: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4130: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4140: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4150: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4170: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
4180: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41a0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
41c0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
41d0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
41e0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
41f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4220: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4230: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4240: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4250: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4260: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4270: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4280: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
42a0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
42b0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
42c0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
42e0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
42f0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4300: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4320: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4330: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4340: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4350: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4360: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4370: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4380: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4390: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
43b0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
43c0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
43d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
43f0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4400: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4410: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4440: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4450: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4460: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4480: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4490: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
44a0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
44b0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
44d0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
44e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
44f0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4500: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4520: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4530: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4540: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4570: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4580: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4590: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
45a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
45c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
45d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
45e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4600: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4610: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4620: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4630: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4640: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4650: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4660: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4680: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4690: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
46a0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
46c0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
46d0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
46e0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
46f0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4700: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4710: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4720: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4730: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4750: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4760: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4770: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4780: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4790: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
47a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
47b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
47c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
47d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
47e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
47f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4800: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4810: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4820: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4830: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4850: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4860: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4870: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4880: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4890: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
48a0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
48b0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
48c0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
48d0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
48e0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
48f0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4900: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4910: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4920: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4930: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4940: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4950: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4960: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4980: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4990: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
49a0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
49b0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
49c0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
49d0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
49e0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
49f0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4a00: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
4a10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4a20: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4a30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4a40: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4a50: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4a90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4aa0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4ab0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ac0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4ad0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4ae0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4af0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4b00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4b10: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4b20: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4b30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4b40: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4b50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4b60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4b70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4b80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4b90: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4ba0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4bb0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4bc0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4bd0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4be0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4bf0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4c00: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4c10: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4c20: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4c30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4c40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4c50: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4c60: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4c70: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4c80: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4c90: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4ca0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4cb0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4cc0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4cd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ce0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4cf0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4d00: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4d10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d20: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4d30: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4d40: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d60: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4d70: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4d80: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4d90: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4db0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4dc0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4dd0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4de0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4df0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4e00: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4e10: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4e20: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4e30: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4e40: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4e50: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4e60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
4e70: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4e80: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4ea0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
4eb0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
4ec0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
4ed0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
4ee0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
4ef0: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
4f00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f10: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
4f20: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4f30: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
4f40: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4f50: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f60: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
4f70: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
4f80: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
4f90: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
4fa0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fc0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
4fd0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4fe0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4ff0: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5000: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5010: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5020: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5030: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5040: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5060: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5080: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
50a0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
50b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5120: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5160: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5250: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52d0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5310: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5320: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5330: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5350: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5370: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5390: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
53a0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
53b0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
53c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53d0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
53e0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
53f0: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5400: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5410: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5420: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5430: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5460: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5470: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5480: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5490: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
54a0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
54b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
54c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
54e0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
54f0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5510: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5520: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5550: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5570: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
55a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
55b0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5610: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5630: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5640: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5660: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5670: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5690: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56a0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
56c0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
56d0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
56e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
56f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5700: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5710: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5720: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5730: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  08000../*.** CAP
5740: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5750: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5760: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5770: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5780: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
57a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
57c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
57d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
57e0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
57f0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5800: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5810: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5830: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5840: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5860: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5870: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
58a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
58b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
58c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
58d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
58e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
58f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
59a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
59b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
59c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
59d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
59e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
59f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ab0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ad0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5ae0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b00: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5b10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5b40: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b60: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5b70: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b90: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5ba0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5bd0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bf0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5c00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5c30: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c50: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
5c60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
5c90: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5cb0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
5cc0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
5cd0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5ce0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
5cf0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
5d00: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
5d10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5d20: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5d30: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5d40: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5d50: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
5d60: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
5d70: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
5d80: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
5d90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5da0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5dc0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
5dd0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
5de0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
5df0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5e10: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e30: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e50: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
5e60: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
5e70: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
5e80: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
5e90: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
5ea0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
5eb0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
5ec0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
5ed0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
5ee0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5ef0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
5f00: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
5f10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5f20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5f30: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
5f40: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
5f50: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5f60: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
5f70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
5f80: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
5f90: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
5fa0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
5fb0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
5fc0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
5fd0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
5fe0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
5ff0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
6000: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
6010: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6020: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
6030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6040: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
6050: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
6060: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6070: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6080: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
60b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60c0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
60d0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
60e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
60f0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6100: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6110: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6120: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6130: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
6140: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
6150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6160: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6170: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6180: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
6190: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
61a0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
61b0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
61c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
61d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
61e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
61f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
6200: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
6210: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
6220: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
6230: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
6240: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
6250: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6260: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6270: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6280: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6290: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
62a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
62b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
62c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
62d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
62e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
62f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
6300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6310: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
6320: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
6330: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
6340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6350: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6360: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6370: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
6380: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
6390: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
63a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
63b0: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
63c0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
63d0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
63e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
63f0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6400: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6420: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6440: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6450: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6460: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6470: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6480: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6490: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
64a0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
64b0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
64c0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
64d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
64e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
64f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
6500: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
6510: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
6520: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
6530: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
6540: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
6550: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
6560: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
6570: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
6580: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
6590: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
65a0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
65b0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
65c0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
65d0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
65e0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
65f0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
6600: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
6610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
6620: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
6630: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
6640: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6650: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
6660: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6670: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
6680: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
6690: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
66c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
66e0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
66f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6700: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6710: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6720: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6730: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
6740: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
6750: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
6760: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
6770: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
6780: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
6790: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
67a0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
67b0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
67c0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
67d0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
67e0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
67f0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6800: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6810: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6820: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6830: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
6840: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
6850: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
6860: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
6870: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
6880: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
6890: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
68a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
68b0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
68c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
68d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
68e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
68f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6900: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6910: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6920: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6930: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
6940: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
6950: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
6960: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
6970: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
6980: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
6990: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
69a0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
69b0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
69c0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
69d0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
69e0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
69f0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6a00: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6a10: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6a20: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6a30: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
6a40: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
6a50: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
6a60: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
6a70: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
6a80: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
6a90: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6aa0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6ab0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6ac0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6ad0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6ae0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6af0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b10: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6b20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6b30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
6b40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
6b50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
6b60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
6b70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
6b80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
6b90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6ba0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6bb0: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6bc0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6bd0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6be0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6bf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6c00: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6c10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6c20: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6c30: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
6c40: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
6c50: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
6c60: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
6c70: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
6c80: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
6c90: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6ca0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6cb0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6cc0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6cd0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6ce0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6cf0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6d00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6d20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6d40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6d60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6da0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6dc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6de0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6e00: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e20: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6e40: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
6e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
6e60: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
6e70: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
6e80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6ea0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6eb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6ec0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6ed0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ee0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6ef0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6f00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6f10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6f20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6f30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6f40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6f50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6f60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6f70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6f90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6fa0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6fb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6fc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6fd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6fe0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6ff0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7000: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7010: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7020: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7030: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7040: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7060: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7070: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7080: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7090: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
70a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
70b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
70c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
70d0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
70e0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
70f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7100: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
7110: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
7120: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
7130: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
7140: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
7150: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7160: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7170: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7180: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7190: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
71a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
71b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
71c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
71d0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
71e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
71f0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
7200: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
7210: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
7220: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7230: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
7240: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7250: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7260: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7280: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
72b0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
72c0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
72d0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
72e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
72f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
7300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
7310: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
7320: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
7330: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7340: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
7350: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7360: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7370: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
7380: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7390: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
73a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
73b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
73c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
73d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
73e0: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30  {H11310} <S30800
73f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  >.**.** These in
7400: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7410: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7420: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7430: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7450: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7460: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7480: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
74a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
74b0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
74c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
74d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
74e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
74f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7500: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7510: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7520: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7530: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7540: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7550: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7570: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7580: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7590: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
75a0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
75b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
75c0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
75d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
75e0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
75f0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7600: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7610: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7620: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7630: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7640: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7660: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7670: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
7680: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
7690: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31  e {H17110} <S201
76a0: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  30>.**.** The mu
76b0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
76c0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
76d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
76e0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
76f0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
7700: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
7710: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
7720: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
7730: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
7740: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
7750: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
7760: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
7770: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
7780: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
7790: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
77a0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
77b0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
77c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
77d0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
77e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
77f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
7800: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
7810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7820: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
7830: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30   {H11140} <S2010
7840: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0>.**.** An inst
7850: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
7860: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
7870: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
7880: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
7890: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
78a0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
78b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
78c0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
78d0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
78e0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
78f0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7900: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7910: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
7920: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
7930: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
7940: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
7950: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
7960: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
7970: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
7980: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
7990: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
79a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
79b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
79c0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
79d0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
79e0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
79f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7a00: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
7a10: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
7a20: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
7a30: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
7a40: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
7a50: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
7a60: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
7a70: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
7a80: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
7a90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
7aa0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
7ab0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
7ac0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
7ad0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
7ae0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
7af0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
7b00: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
7b10: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
7b20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
7b30: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
7b40: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
7b50: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
7b60: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
7b70: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7b80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
7b90: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
7ba0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
7bb0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
7bc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
7bd0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
7be0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
7bf0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
7c00: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
7c10: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
7c20: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
7c30: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
7c40: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
7c50: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
7c60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
7c70: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
7c80: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
7c90: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
7ca0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
7cb0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
7cc0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
7cd0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7ce0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7cf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7d00: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7d10: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7d20: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7d30: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7d40: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
7d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
7d60: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7d70: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
7d80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7d90: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
7da0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7db0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7dd0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7de0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7df0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7e00: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7e10: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7e20: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7e30: 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74  * {H11141} SQLit
7e40: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7e50: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
7e60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
7e70: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
7e80: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
7e90: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
7ea0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
7eb0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
7ec0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
7ed0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
7ee0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
7ef0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
7f00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
7f10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
7f20: 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63  lled. {END}  Bec
7f30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
7f40: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a  ious sentense,.*
7f50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
7f60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
7f70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
7f80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
7f90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
7fa0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
7fb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
7fc0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
7fd0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
7fe0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
7ff0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8000: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8010: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20  must invite its 
8020: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8030: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8040: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
8050: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
8060: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
8070: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
8080: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
8090: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
80a0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
80b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
80c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
80d0: 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65  .** {H11142} The
80e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
80f0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8100: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
8110: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
8120: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
8130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
8140: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8150: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8170: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8180: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
8190: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
81a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
81b0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
81c0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44  EN_CREATE]. {END
81d0: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  }.** If xOpen() 
81e0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
81f0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8200: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
8210: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
8220: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
8230: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
8240: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
8250: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8260: 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {H11143} SQLite
8270: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
8280: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
8290: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
82a0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
82b0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
82c0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
82d0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
82e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
82f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8300: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8310: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8320: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8340: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8360: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8370: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8380: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
8390: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
83a0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
83b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
83c0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
83d0: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NAL].** </ul> {E
83e0: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ND}.**.** The fi
83f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
8400: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
8410: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
8420: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
8430: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
8440: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
8450: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
8460: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
8470: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
8480: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
8490: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
84a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
84b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
84c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
84d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
84e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
84f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
8500: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
8510: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
8520: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
8530: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
8540: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
8560: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
8570: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
8580: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
8590: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
85a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
85b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
85c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
85d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
85e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
85f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
8600: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
8610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8630: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
8640: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
8650: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8670: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8690: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
86a0: 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b  * {H11145} The [
86b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
86c0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
86d0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
86e0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
86f0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8700: 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d  losed.  {H11146}
8710: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8720: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8730: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8740: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8750: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8760: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8770: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37  s..**.** {H11147
8780: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
8790: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
87a0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
87b0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
87c0: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  ed.** for exclus
87d0: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69  ive access.  Thi
87e0: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f  s flag is set fo
87f0: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65  r all files exce
8800: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61  pt.** for the ma
8810: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
8820: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d  ..**.** {H11148}
8830: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
8840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
8850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
8860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
8870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
8880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
8890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
88a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
88b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45  ent to xOpen. {E
88c0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
88d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
88e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
88f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
8900: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
8910: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
8920: 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20  ** {H11149} The 
8930: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8940: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8950: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8960: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
8970: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
8980: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
8990: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
89a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
89b0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
89c0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
89d0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
89e0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
89f0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8a00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8a10: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8a20: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d   readable. {END}
8a30: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8a40: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8a50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d  ..**.** {H11150}
8a60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8a70: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8a80: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8a90: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8aa0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ab0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8ac0: 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 78   {H11151} The ex
8ad0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8af0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8b00: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8b10: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8b20: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f   {END}  If the o
8b30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8b40: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8b50: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8b60: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8b70: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8b80: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8b90: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8ba0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8bb0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8bc0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8bd0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8be0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8bf0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8c00: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8c10: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8c20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8c30: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8c40: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8c50: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8c60: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8c70: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8c80: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8c90: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ca0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8cb0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8cc0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8cd0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8ce0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8cf0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8d00: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8d10: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8d20: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8d30: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8d40: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8d50: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8d60: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8d70: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8d80: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8d90: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8da0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
8db0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8dc0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8dd0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8de0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8df0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8e00: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8e10: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8e20: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8e30: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8e50: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e60: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
8e70: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e80: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8e90: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
8ea0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
8eb0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
8ec0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
8ed0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
8ee0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
8ef0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
8f00: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
8f10: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
8f20: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
8f30: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
8f40: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
8f50: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
8f60: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
8f70: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
8f80: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
8f90: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
8fa0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
8fb0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
8fc0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
8fd0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
8fe0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
8ff0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9000: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9020: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9030: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9040: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9050: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9060: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9070: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9080: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9090: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
90a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
90b0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
90c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
90d0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
90e0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
90f0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9100: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9120: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9130: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9140: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9160: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9170: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9180: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9190: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
91a0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
91b0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
91c0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
91d0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
91e0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
91f0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9200: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9210: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9220: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9230: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9240: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9250: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9260: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9270: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9280: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9290: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
92a0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
92b0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
92c0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
92d0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
92e0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
92f0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9300: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
9310: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
9320: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
9330: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
9340: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
9350: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
9360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9370: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
9380: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
9390: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e  H11190} <H11140>
93a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20  .**.** {H11191} 
93b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
93c0: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
93d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
93e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
93f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9400: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9410: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9420: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65  {END}  They dete
9430: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
9440: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
9450: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9460: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9470: 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d  for..** {H11192}
9480: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9490: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
94a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
94b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
94c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
94d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31   exists..** {H11
94e0: 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45  193} With SQLITE
94f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9500: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9510: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9520: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9530: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9540: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9550: 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68  ** {H11194} With
9560: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9570: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
9580: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
9590: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
95a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
95b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
95c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
95d0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
95e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
95f0: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
9600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9610: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
9620: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
9630: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
9640: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d  Library {H10130}
9650: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30   <S20000><S30100
9660: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
9670: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9680: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9690: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
96a0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
96c0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
96d0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
96e0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
96f0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9700: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9710: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
9720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
9730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
9740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
9760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
9790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
97a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
97b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
97c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
97d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
97e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
97f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9810: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9820: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9830: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9850: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9860: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9870: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
9880: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
9890: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
98a0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
98b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
98c0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
98e0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
98f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9900: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
9910: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9930: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9940: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9950: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
9960: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72  ccess..** If for
9970: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
9980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9990: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
99a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
99b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
99c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
99d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
99e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
99f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
9a00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
9a10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
9a20: 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f  er than SQLITE_O
9a30: 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  K..**.** The sql
9a40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a50: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
9a60: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
9a70: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
9a80: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9a90: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
9aa0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
9ab0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
9ac0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
9ad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ae0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
9af0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
9b00: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
9b10: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
9b20: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
9b30: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
9b40: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
9b50: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
9b60: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
9b70: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
9b80: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
9b90: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
9ba0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
9bb0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
9bc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9bd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
9be0: 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d  _AUTOINIT.** com
9bf0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
9c00: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
9c10: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
9c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c30: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
9c40: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
9c50: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
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 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
9c80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
9c90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
9ca0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
9cb0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
9cc0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
9cd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
9ce0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
9cf0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
9d00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
9d10: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
9d20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
9d30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9d40: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
9d50: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
9d60: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
9d70: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
9d80: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
9d90: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
9da0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
9db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53   compiled with S
9dc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9dd0: 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  NIT might become
9de0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
9df0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
9e00: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
9e10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
9e20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
9e30: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
9e40: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
9e50: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
9e60: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9e70: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
9e80: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
9e90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
9ea0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
9eb0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
9ec0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
9ed0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
9ee0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
9ef0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
9f00: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
9f10: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
9f20: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
9f30: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
9f40: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
9f50: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
9f60: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
9f70: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
9f80: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
9f90: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
9fa0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
9fb0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
9fc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
9fd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
9fe0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
9ff0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a000: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a010: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a020: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a030: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a040: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a050: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a060: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a070: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a080: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a090: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a0a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a0b0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a0c0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a0d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a0f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a110: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a120: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a130: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a140: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a150: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a160: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a170: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a180: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a190: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a1a0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a1b0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a1c0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a1d0: 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  the SQLITE_OS_OT
a1e0: 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69  HER=1 compile-ti
a1f0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a200: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a210: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a220: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a230: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a260: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a270: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a280: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a2a0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a2b0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a2c0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
a2d0: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
a2e0: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
a2f0: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
a300: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
a310: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a320: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
a330: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
a340: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a350: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
a360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
a370: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
a380: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
a390: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
a3a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34  e Library {H1014
a3b0: 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32  5} <S20000><S302
a3c0: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a3d0: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
a3e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a3f0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a400: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a420: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a430: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a440: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a450: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a460: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a470: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a480: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a490: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a4a0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a4b0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a4c0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a4d0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a4e0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a4f0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a500: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a510: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a520: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a530: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a540: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a550: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a560: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a570: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a580: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a590: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a5a0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a5b0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a5c0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a5d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a5e0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a5f0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a600: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a610: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a620: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a630: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a640: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a650: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a660: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a670: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a680: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65  down()]..** Note
a690: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
a6a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a6b0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
a6c0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
a6d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6e0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
a6f0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
a700: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
a710: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
a720: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
a730: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
a740: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
a750: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
a760: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
a770: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
a780: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
a790: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
a7a0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
a7b0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
a7c0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
a7d0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
a7e0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
a7f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a800: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
a810: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a820: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
a830: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
a840: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69  .** When a confi
a850: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
a860: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
a870: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
a880: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
a890: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a8a0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a8b0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a8c0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
a8d0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
a8e0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
a8f0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
a900: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
a910: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
a920: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
a930: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
a940: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a950: 69 6f 6e 73 20 20 7b 48 31 30 31 38 30 7d 20 3c  ions  {H10180} <
a960: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
a970: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a980: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
a990: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a9a0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
a9b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a9c0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
a9d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a9e0: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
a9f0: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
aa00: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
aa10: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
aa20: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
aa30: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
aa40: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
aa50: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
aa60: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
aa70: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54  st argument).  T
aa80: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62  he.** sqlite3_db
aa90: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
aaa0: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ace can only be 
aab0: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  used immediately
aac0: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61   after.** the da
aad0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
aae0: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  n is created usi
aaf0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
ab00: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
ab10: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
ab20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
ab30: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
ab40: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
ab50: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
ab60: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
ab70: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  s the.** configu
ab80: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e  ration verb - an
ab90: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
aba0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
abb0: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74  t.** aspect of t
abc0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
abd0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
abe0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
abf0: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65   The only choice
ac00: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20   for this value 
ac10: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  is [SQLITE_DBCON
ac20: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a  FIG_LOOKASIDE]..
ac30: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65  ** New verbs are
ac40: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64   likely to be ad
ac50: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
ac60: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
ac70: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
ac80: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64  arguments depend
ac90: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2f   on the verb..*/
aca0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
acb0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
acc0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
acd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ace0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
acf0: 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 31  n Routines {H101
ad00: 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20  55} <S20120>.** 
ad10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
ad20: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
ad30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
ad40: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ad50: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
ad60: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
ad70: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
ad80: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
ad90: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
ada0: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
adb0: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
adc0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
add0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
ade0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
adf0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
ae00: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
ae10: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
ae20: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
ae30: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
ae40: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
ae50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
ae60: 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e  OC].  By creatin
ae70: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
ae80: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
ae90: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
aea0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
aeb0: 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66  g()] during conf
aec0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a  iguration, an.**
aed0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
aee0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
aef0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61  rnative memory a
af00: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
af10: 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74  tem.** for SQLit
af20: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
af30: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
af40: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
af50: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
af60: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
af70: 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  a built-in memor
af80: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
af90: 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79   is.** perfectly
afa0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
afb0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
afc0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
afd0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
afe0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
aff0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
b000: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
b010: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
b020: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
b030: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
b040: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
b050: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
b060: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
b070: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b080: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
b090: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
b0a0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
b0b0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
b0c0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
b0d0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
b0e0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
b0f0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
b100: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
b110: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
b120: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
b130: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
b140: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
b150: 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78  oc, xFree, and x
b160: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20  Realloc methods 
b170: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
b180: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
b190: 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c  free(), and real
b1a0: 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  loc() functions 
b1b0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
b1c0: 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  d library..**.**
b1d0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
b1e0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
b1f0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
b200: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
b210: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
b220: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
b230: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
b240: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
b250: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
b260: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
b270: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
b280: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
b290: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
b2a0: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
b2b0: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
b2c0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
b2d0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
b2e0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
b2f0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
b300: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
b310: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
b320: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
b330: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
b340: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
b350: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
b360: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
b370: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
b380: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
b390: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
b3a0: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
b3b0: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a  ower of 2..**.**
b3c0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
b3d0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
b3e0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b3f0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
b400: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
b410: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
b420: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
b430: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
b440: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
b450: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
b460: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b470: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
b480: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
b490: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b4a0: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
b4b0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
b4c0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
b4d0: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
b4e0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
b4f0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
b500: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
b510: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
b520: 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65  hutdown..*/.type
b530: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b540: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
b550: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
b560: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
b570: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
b580: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
b590: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
b5a0: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
b5b0: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
b5c0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
b5d0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
b5e0: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
b5f0: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
b600: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
b610: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
b620: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
b630: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
b640: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
b650: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
b660: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
b670: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
b680: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
b690: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
b6a0: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
b6b0: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
b6c0: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
b6d0: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
b6e0: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
b6f0: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
b700: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
b710: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
b720: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
b730: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
b740: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
b750: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b760: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
b770: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
b780: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
b790: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
b7a0: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
b7b0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
b7c0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
b7d0: 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31  on Options {H101
b7e0: 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  60} <S20000>.** 
b7f0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
b800: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
b810: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
b820: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
b830: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
b840: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
b850: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
b860: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
b870: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
b880: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
b890: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
b8a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b8b0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
b8c0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
b8d0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
b8e0: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
b8f0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
b900: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
b910: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
b920: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
b930: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
b940: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
b950: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
b960: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
b970: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
b980: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
b990: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
b9a0: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
b9b0: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
b9c0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
b9d0: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
b9e0: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
b9f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
ba00: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
ba10: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
ba20: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ba30: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
ba40: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
ba50: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
ba60: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ba70: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64  .  This option d
ba80: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
ba90: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
baa0: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
bab0: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
bac0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
bad0: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
bae0: 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ead.</dd>.**.** 
baf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
bb00: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
bb10: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
bb20: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
bb30: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
bb40: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69    This option di
bb50: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
bb60: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
bb70: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
bb80: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bb90: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
bba0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbb0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
bbc0: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
bbd0: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
bbe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bbf0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
bc00: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
bc10: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
bc20: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
bc30: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
bc40: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
bc50: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
bc60: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
bc70: 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  onment.</dd>.**.
bc80: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bc90: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
bca0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
bcb0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
bcc0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
bcd0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
bce0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
bcf0: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
bd00: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
bd10: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
bd20: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bd30: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
bd40: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
bd50: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
bd60: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
bd70: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
bd80: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
bd90: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
bda0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
bdb0: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
bdc0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
bdd0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
bde0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
bdf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
be00: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
be10: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
be20: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
be30: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
be40: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
be50: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
be60: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
be70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
be80: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
be90: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
bea0: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a  e same time..**.
beb0: 2a 2a 20 3c 70 3e 54 68 69 73 20 63 6f 6e 66 69  ** <p>This confi
bec0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
bed0: 6d 65 72 65 6c 79 20 73 65 74 73 20 74 68 65 20  merely sets the 
bee0: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 0a 2a  default mutex .*
bef0: 2a 20 62 65 68 61 76 69 6f 72 20 74 6f 20 73 65  * behavior to se
bf00: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 20 74  rialize access t
bf10: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
bf20: 65 63 74 69 6f 6e 73 5d 2e 20 20 49 6e 64 69 76  ections].  Indiv
bf30: 69 64 75 61 6c 0a 2a 2a 20 5b 64 61 74 61 62 61  idual.** [databa
bf40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
bf50: 63 61 6e 20 6f 76 65 72 72 69 64 65 20 74 68 69  can override thi
bf60: 73 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 73 69  s setting.** usi
bf70: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
bf80: 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
bf90: 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  g to [sqlite3_op
bfa0: 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70 3e 3c 2f 64  en_v2()].</p></d
bfb0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
bfc0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
bfd0: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  C</dt>.** <dd>Th
bfe0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
bff0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c000: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c010: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c020: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c030: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c040: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c050: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
c060: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
c070: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
c080: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c090: 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
c0a0: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
c0b0: 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
c0c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
c0d0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
c0e0: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  QLite.</dd>.**.*
c0f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c100: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
c110: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c120: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
c130: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
c140: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
c150: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
c160: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
c170: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
c180: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
c190: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
c1a0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
c1b0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
c1c0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
c1d0: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
c1e0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
c1f0: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  es..** This opti
c200: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
c210: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
c220: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
c230: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
c240: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
c250: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
c260: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
c270: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
c280: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
c290: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
c2a0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
c2b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c2c0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
c2d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c2e0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
c2f0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
c300: 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
c310: 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
c320: 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
c330: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
c340: 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
c350: 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
c360: 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
c370: 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c  ics. When disabl
c380: 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
c390: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
c3a0: 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e  ces become .** n
c3b0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
c3c0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
c3d0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c3e0: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
c3f0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
c400: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
c410: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
c420: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
c430: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c  limit()].**   <l
c440: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
c450: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
c460: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
c470: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c480: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
c490: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c4a0: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
c4b0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
c4c0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
c4d0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
c4e0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
c4f0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
c500: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
c510: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
c520: 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20  ry, the.** size 
c530: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
c540: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
c550: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
c560: 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65  uffers (N).  The
c570: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
c580: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
c590: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a  le of 16. The sz
c5a0: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
c5b0: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73  d be a few bytes
c5c0: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20  .** larger than 
c5d0: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74  the actual scrat
c5e0: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ch space require
c5f0: 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f  d due internal o
c600: 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20  verhead..** The 
c610: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
c620: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
c630: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
c640: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
c650: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
c660: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
c670: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
c680: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
c690: 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72  ffer at once per
c6a0: 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e   thread, so.** N
c6b0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
c6c0: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  o the expected m
c6d0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c6e0: 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73   threads.  The s
c6f0: 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73  z.** parameter s
c700: 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73  hould be 6 times
c710: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c720: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
c730: 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
c740: 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  Scratch buffers 
c750: 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74  are used as part
c760: 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61   of the btree ba
c770: 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e  lance operation.
c780: 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65    If.** The btre
c790: 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73  e balancer needs
c7a0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   additional memo
c7b0: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
c7c0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a  s provided by.**
c7d0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
c7e0: 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63   or if no scratc
c7f0: 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69  h buffer space i
c800: 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
c810: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73  n SQLite.** goes
c820: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
c830: 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e  loc()] to obtain
c840: 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e   the memory it n
c850: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eeds.</dd>.**.**
c860: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c870: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
c880: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c890: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
c8a0: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
c8b0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
c8c0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
c8d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
c8e0: 67 65 20 63 61 63 68 65 2e 20 20 54 68 65 72 65  ge cache.  There
c8f0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
c900: 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20  ents: A pointer 
c910: 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  to the.** memory
c920: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
c930: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
c940: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
c950: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
c960: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
c970: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
c980: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
c990: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
c9a0: 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  8.  The first.**
c9b0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
c9c0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
c9d0: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
c9e0: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
c9f0: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
ca00: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
ca10: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
ca20: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
ca30: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
ca40: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
ca50: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
ca60: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
ca70: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
ca80: 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61  e.  If additiona
ca90: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
caa0: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
cab0: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
cac0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
cad0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
cae0: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
caf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
cb00: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
cb10: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
cb20: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  ace..** The impl
cb30: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
cb40: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   use one or more
cb50: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72   of the N buffer
cb60: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65  s to hold .** me
cb70: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
cb80: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64  information. </d
cb90: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cba0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
cbb0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
cbc0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
cbd0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
cbe0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
cbf0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
cc00: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
cc10: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
cc20: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
cc30: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
cc40: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
cc50: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
cc60: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
cc70: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
cc80: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
cc90: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
cca0: 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  nts: A pointer t
ccb0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
ccc0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
ccd0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
cce0: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
ccf0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
cd00: 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a  ation size.  If.
cd10: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  ** the first poi
cd20: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
cd30: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
cd40: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
cd50: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
cd60: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
cd70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
cd80: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
cd90: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
cda0: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
cdb0: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
cdc0: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
cdd0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
cde0: 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f    If the.** memo
cdf0: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
ce00: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
ce10: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
ce20: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
ce30: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
ce40: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
ce50: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
ce60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ce70: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
ce80: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
ce90: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
cea0: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
ceb0: 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a  ion needs.</dd>.
cec0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ced0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
cee0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
cef0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
cf00: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
cf10: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
cf20: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
cf30: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
cf40: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
cf50: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
cf60: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
cf70: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
cf80: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
cf90: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
cfa0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
cfb0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
cfc0: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
cfd0: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
cfe0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
cff0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
d000: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d010: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d020: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d030: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d040: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
d050: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
d060: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d070: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
d080: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
d090: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
d0a0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
d0b0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
d0c0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
d0d0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
d0e0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
d0f0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
d100: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
d110: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
d120: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
d130: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
d140: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
d150: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
d160: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
d170: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
d180: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  g, for example.<
d190: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d1a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
d1b0: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
d1c0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d1d0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
d1e0: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
d1f0: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
d200: 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f   memory allcatio
d210: 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69  n lookaside opti
d220: 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66  mization.  The f
d230: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
d240: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
d250: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
d260: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
d270: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
d280: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
d290: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
d2a0: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
d2b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  onnection.</dd>.
d2c0: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d2e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
d2f0: 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
d300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d310: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
d320: 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
d330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d340: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
d350: 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
d360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d370: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
d380: 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
d390: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
d3a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d3b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
d3c0: 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
d3d0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
d3e0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
d3f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
d400: 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
d410: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
d420: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
d430: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
d440: 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
d450: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
d460: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
d470: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d480: 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
d490: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
d4a0: 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
d4b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d4c0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
d4d0: 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
d4e0: 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
d4f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
d500: 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
d510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
d520: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d530: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d540: 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
d550: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d560: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
d570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d580: 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 20  FIG_CHUNKALLOC  
d590: 20 31 32 20 20 2f 2a 20 69 6e 74 20 74 68 72 65   12  /* int thre
d5a0: 73 68 6f 6c 64 20 2a 2f 0a 23 64 65 66 69 6e 65  shold */.#define
d5b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
d5c0: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
d5d0: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 2f  /* int int */../
d5e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d5f0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
d600: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53  ions {H10170} <S
d610: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
d620: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
d630: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
d640: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
d650: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
d660: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
d670: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
d680: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
d690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
d6a0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
d6b0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
d6c0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
d6d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d6e0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
d6f0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
d700: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
d710: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
d720: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
d730: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
d740: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
d750: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
d760: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
d770: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
d780: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
d790: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
d7a0: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
d7b0: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
d7c0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
d7d0: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
d7e0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
d7f0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
d800: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
d810: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
d820: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
d830: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
d840: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
d850: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
d860: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
d870: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
d880: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d890: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
d8a0: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
d8b0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
d8c0: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
d8d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
d8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
d8f0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
d900: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
d910: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d920: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
d930: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
d940: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
d950: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
d960: 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
d970: 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
d980: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20  okaside memory. 
d990: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
d9a0: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
d9b0: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
d9c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
d9d0: 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73  ocate the lookas
d9e0: 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74  ide.** buffer it
d9f0: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
da00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
da10: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
da20: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
da30: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
da40: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
da50: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61   and the third a
da60: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
da70: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
da80: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
da90: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
daa0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
dab0: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
dac0: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
dad0: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
dae0: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
daf0: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
db00: 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ts.</dd>.**.** <
db10: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
db20: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
db30: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30  LOOKASIDE    100
db40: 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
db50: 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
db60: 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
db70: 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
db80: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
db90: 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30   {H12200} <S1070
dba0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
dbb0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
dbc0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
dbd0: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
dbe0: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
dbf0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
dc00: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
dc10: 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65  of SQLite. The e
dc20: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
dc30: 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
dc40: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
dc50: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
dc60: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e  ompatibility con
dc70: 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  siderations..**.
dc80: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
dc90: 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61  *.** {H12201} Ea
dca0: 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
dcb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61   connection] sha
dcc0: 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20  ll have the.**  
dcd0: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
dce0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
dcf0: 66 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64  feature disabled
dd00: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
dd10: 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20  ** {H12202} The 
dd20: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
dd30: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44  d_result_codes(D
dd40: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ,F)] interface s
dd50: 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20  hall enable.**  
dd60: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
dd70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
dd80: 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61  for the  [databa
dd90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
dda0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
ddb0: 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20  the F parameter 
ddc0: 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61  is true, or disa
ddd0: 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73  ble them if F is
dde0: 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73   false..*/.int s
ddf0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
de00: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
de10: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
de20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
de30: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
de40: 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c  Rowid {H12220} <
de50: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61  S10700>.**.** Ea
de60: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
de70: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
de80: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
de90: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
dea0: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
deb0: 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f   "rowid". The ro
dec0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
ded0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
dee0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
def0: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
df00: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
df10: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
df20: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
df30: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
df40: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
df50: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
df60: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
df70: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
df80: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
df90: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
dfa0: 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
dfb0: 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
dfc0: 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  e rowid..**.** T
dfd0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
dfe0: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66  rns the rowid of
dff0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e000: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49  .** successful I
e010: 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64  NSERT into the d
e020: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
e030: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e040: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
e050: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
e060: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
e070: 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61  ul INSERTs.** ha
e080: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
e090: 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
e0a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
e0b0: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
e0c0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45  **.** If an INSE
e0d0: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  RT occurs within
e0e0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
e0f0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
e100: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
e110: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
e120: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
e130: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
e140: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
e150: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
e160: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
e170: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
e180: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
e190: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
e1a0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
e1b0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
e1c0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
e1d0: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
e1e0: 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61 69   INSERT that fai
e1f0: 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
e200: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
e210: 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
e220: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61  cessful INSERT a
e230: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
e240: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
e250: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
e260: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
e270: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
e280: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
e290: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
e2a0: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
e2b0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
e2c0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
e2d0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
e2e0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
e2f0: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
e300: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
e310: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
e320: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
e330: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
e340: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
e350: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
e360: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
e370: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
e380: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
e390: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
e3a0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
e3b0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
e3c0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
e3d0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
e3e0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
e3f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
e400: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
e410: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
e420: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
e430: 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52  outine, an INSER
e440: 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  T is considered 
e450: 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
e460: 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
e470: 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
e480: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
e490: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
e4a0: 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65  .** {H12221} The
e4b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
e4c0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
e4d0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
e4e0: 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20  the rowid.**    
e4f0: 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73        of the mos
e500: 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
e510: 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f  ful INSERT perfo
e520: 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  rmed on the same
e530: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
e540: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e550: 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  n] and within th
e560: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
e570: 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20   level.**       
e580: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
e590: 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
e5a0: 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e  here have been n
e5b0: 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73  o qualifying ins
e5c0: 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  erts..**.** {H12
e5d0: 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  223} The [sqlite
e5e0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
e5f0: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
e600: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
e610: 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c          same val
e620: 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  ue when called f
e630: 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69  rom the same tri
e640: 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  gger context.** 
e650: 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61           immedia
e660: 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20  tely before and 
e670: 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b  after a ROLLBACK
e680: 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
e690: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
e6a0: 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
e6b0: 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
e6c0: 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f  s a new INSERT o
e6d0: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
e6e0: 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
e6f0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
e700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
e710: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
e720: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  )].**          f
e730: 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
e740: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
e750: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
e760: 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20  ert rowid,.**   
e770: 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
e780: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
e790: 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
e7a0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
e7b0: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  is.**          u
e7c0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
e7d0: 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
e7e0: 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
e7f0: 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20  or the new.**   
e800: 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65         last inse
e810: 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c  rt rowid..*/.sql
e820: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
e830: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
e840: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
e850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e860: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
e870: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
e880: 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30  ed {H12240} <S10
e890: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
e8a0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e8b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
e8c0: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
e8d0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
e8e0: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
e8f0: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
e900: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
e910: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
e920: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
e930: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e940: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
e950: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
e960: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20  ameter..** Only 
e970: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
e980: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
e990: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
e9a0: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72  T, UPDATE,.** or
e9b0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
e9c0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
e9d0: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
e9e0: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
e9f0: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
ea00: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
ea10: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
ea20: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
ea30: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
ea40: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
ea50: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
ea60: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
ea70: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
ea80: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68  .**.** A "row ch
ea90: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
eaa0: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
eab0: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
eac0: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
ead0: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
eae0: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
eaf0: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
eb00: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
eb10: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
eb20: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  ts of REPLACE co
eb30: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
eb40: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
eb50: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
eb60: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20  ng, DROP TABLE, 
eb70: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
eb80: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
eb90: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
eba0: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
ebb0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
ebc0: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
ebd0: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
ebe0: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
ebf0: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
ec00: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
ec10: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20   trigger.  Most 
ec20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
ec30: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
ec40: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
ec50: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
ec60: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
ec70: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
ec80: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
ec90: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
eca0: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
ecb0: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
ecc0: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
ecd0: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
ece0: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
ecf0: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
ed00: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
ed10: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
ed20: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
ed30: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
ed40: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
ed50: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
ed60: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
ed70: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
ed80: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
ed90: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
eda0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
edb0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
edc0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
edd0: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
ede0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
edf0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
ee00: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
ee10: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
ee20: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
ee30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68  ..**.** Thus, wh
ee40: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
ee50: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
ee60: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
ee70: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
ee80: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
ee90: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
eea0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
eeb0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
eec0: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
eed0: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
eee0: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  .  Within the bo
eef0: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
ef00: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
ef10: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
ef20: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
ef30: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
ef40: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
ef50: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
ef60: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
ef70: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
ef80: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
ef90: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
efa0: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
efb0: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
efc0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
efd0: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
efe0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
eff0: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
f000: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
f010: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
f020: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
f030: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
f040: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
f050: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
f060: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
f070: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
f080: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
f090: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
f0a0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
f0b0: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
f0c0: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
f0d0: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
f0e0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
f0f0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
f100: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
f110: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
f120: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
f130: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
f140: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
f150: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
f160: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
f170: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
f180: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
f190: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
f1a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
f1b0: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
f1c0: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
f1d0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
f1e0: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
f1f0: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
f200: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
f210: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
f220: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
f230: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
f240: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
f250: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f260: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
f270: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ad..**.** INVARI
f280: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
f290: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  241} The [sqlite
f2a0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  3_changes()] fun
f2b0: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75  ction shall retu
f2c0: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
f2d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77  .**          row
f2e0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
f2f0: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
f300: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
f310: 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  E,.**          o
f320: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
f330: 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  nt on the same d
f340: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f350: 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
f360: 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61     within the sa
f370: 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69  me or higher tri
f380: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
f390: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
f3a0: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
f3b0: 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61  not been any qua
f3c0: 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e  lifying row chan
f3d0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ges..**.** {H122
f3e0: 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  43} Statements o
f3f0: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
f400: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
f410: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
f420: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
f430: 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20  use shall cause 
f440: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
f450: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
f460: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
f470: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65  ()] to return ze
f480: 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ro, regardless o
f490: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
f4a0: 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73    number of rows
f4b0: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
f4c0: 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  he table..**.** 
f4d0: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
f4e0: 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61  ** {A12252} If a
f4f0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
f500: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
f510: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
f520: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
f530: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
f540: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
f550: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
f560: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
f570: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
f580: 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74      is unpredict
f590: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
f5a0: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
f5b0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f5c0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
f5d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
f5e0: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
f5f0: 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36   Modified {H1226
f600: 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S10600>.**.*
f610: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
f620: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
f630: 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
f640: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
f650: 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72  RT,.** UPDATE or
f660: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
f670: 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
f680: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f690: 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
f6a0: 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c  * The count incl
f6b0: 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
f6c0: 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65   from all trigge
f6d0: 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77  r contexts.  How
f6e0: 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
f6f0: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
f700: 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
f710: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45   to implement RE
f720: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
f730: 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
f740: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
f750: 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20  essing, or DROP 
f760: 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67  table processing
f770: 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73  ..** The changes
f780: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
f790: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74  soon as the stat
f7a0: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
f7b0: 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70   them is.** comp
f7c0: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
f7d0: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
f7e0: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
f7f0: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
f800: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
f810: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
f820: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
f830: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
f840: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f850: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
f860: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
f870: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
f880: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
f890: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
f8a0: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
f8b0: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
f8c0: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
f8d0: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
f8e0: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
f8f0: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
f900: 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74  his.** optimizat
f910: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
f920: 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52  ns in "DELETE FR
f930: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
f940: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
f950: 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65  d.** will not be
f960: 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20   counted by the 
f970: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f980: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
f990: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a  tal_changes()].*
f9a0: 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67  * functions, reg
f9b0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
f9c0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
f9d0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
f9e0: 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65  inally.** in the
f9f0: 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20   table.  To get 
fa00: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
fa10: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
fa20: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
fa30: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
fa40: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
fa50: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
fa60: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
fa70: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
fa80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
fa90: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
faa0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20  .**.** {H12261} 
fab0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
fac0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
fad0: 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
fae0: 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
faf0: 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
fb00: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
fb10: 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
fb20: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
fb30: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
fb40: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
fb50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fb60: 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
fb70: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
fb80: 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
fb90: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
fba0: 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65  ction was create
fbb0: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33  d..**.** {H12263
fbc0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
fbd0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
fbe0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
fbf0: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
fc00: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
fc10: 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e  e shall not chan
fc20: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
fc30: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
fc40: 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f    by [sqlite3_to
fc50: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a  tal_changes()]..
fc60: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
fc70: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34  S:.**.** {A12264
fc80: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
fc90: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
fca0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
fcb0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
fcc0: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
fcd0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
fce0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
fcf0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
fd00: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
fd10: 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
fd20: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
fd30: 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
fd40: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
fd50: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
fd60: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
fd70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
fd80: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
fd90: 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31  unning Query {H1
fda0: 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a  2270} <S30500>.*
fdb0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
fdc0: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
fdd0: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
fde0: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
fdf0: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
fe00: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
fe10: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
fe20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
fe30: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
fe40: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
fe50: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
fe60: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
fe70: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
fe80: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
fe90: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
fea0: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
feb0: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
fec0: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
fed0: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
fee0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
fef0: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
ff00: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
ff10: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
ff20: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
ff30: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
ff40: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
ff50: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
ff60: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
ff70: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
ff80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ff90: 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
ffa0: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
ffb0: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
ffc0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ffd0: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
ffe0: 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
fff0: 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
10000 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
10010 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
10020 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10030 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
10040 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
10050 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
10060 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
10070 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
10080 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
10090 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
100a0 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
100b0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
100c0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
100d0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
100e0 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  RUPT]..** If the
100f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
10100 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
10110 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
10120 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
10130 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
10140 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
10150 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
10160 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
10170 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
10180 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
10190 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  ically..**.** A 
101a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
101b0 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
101c0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
101d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
101e0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
101f0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
10200 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
10210 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
10220 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
10230 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
10240 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
10250 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
10260 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
10270 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
10280 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
10290 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
102a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
102b0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
102c0 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
102d0 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
102e0 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
102f0 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  al row of data..
10300 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41  **.** {H12272} A
10310 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
10320 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
10330 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
10340 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
10350 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
10360 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
10370 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
10380 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
10390 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74  ** {A12279} If t
103a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
103b0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
103c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
103d0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
103e0 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
103f0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
10400 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
10410 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
10420 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
10430 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
10440 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
10450 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
10460 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
10470 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53  lete {H10510} <S
10480 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70200>.**.** The
10490 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
104a0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
104b0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
104c0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
104d0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
104e0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
104f0 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65  s to form comple
10500 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  te a SQL stateme
10510 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
10520 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
10530 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
10540 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
10550 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
10560 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
10570 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
10580 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e  n true if the in
10590 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
105a0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
105b0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
105c0 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
105d0 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
105e0 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
105f0 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
10600 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
10610 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72   and is not a fr
10620 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43  agment of a.** C
10630 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
10640 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
10650 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
10660 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
10670 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
10680 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
10690 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
106a0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
106b0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
106c0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
106d0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
106e0 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
106f0 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
10700 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
10710 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
10720 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
10730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
10740 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
10750 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
10760 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
10770 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
10780 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
10790 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
107a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
107b0 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73  .** {H10511} A s
107c0 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61  uccessful evalua
107d0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
107e0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a  _complete()] or.
107f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10800 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10810 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61  )] functions sha
10820 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ll.**          r
10830 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
10840 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  1 if and only if
10850 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68   the last non-wh
10860 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20  itespace.**     
10870 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68       token in th
10880 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73  eir input is a s
10890 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73  emicolon that is
108a0 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a   not in between.
108b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
108c0 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66  BEGIN and END of
108d0 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45   a CREATE TRIGGE
108e0 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  R statement..**.
108f0 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61  ** {H10512} If a
10900 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10910 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
10920 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61  during an invoca
10930 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
10940 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   of [sqlite3_com
10950 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c  plete()] or [sql
10960 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10970 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  )] then the.**  
10980 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20          routine 
10990 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
109a0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
109b0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
109c0 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54  **.** {A10512} T
109d0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
109e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
109f0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
10a00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
10a10 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
10a20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ing..**.** {A105
10a30 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
10a40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10a50 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
10a60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
10a70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
10a80 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
10a90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
10aa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10ab0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
10ac0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
10ad0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10ae0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
10af0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
10b00 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
10b10 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
10b20 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
10b30 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20  Errors {H12310} 
10b40 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40400>.**.** T
10b50 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
10b60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
10b70 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
10b80 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
10b90 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
10ba0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
10bb0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
10bc0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
10bd0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
10be0 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
10bf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  .**.** If the bu
10c00 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
10c10 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
10c20 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
10c30 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
10c40 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
10c50 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
10c60 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
10c70 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20  he lock. If the 
10c80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
10c90 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
10ca0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
10cb0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
10cc0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
10cd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ts..**.** The fi
10ce0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10cf0 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
10d00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
10d10 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
10d20 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
10d30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10d40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10d50 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  r().  The second
10d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10d70 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  the handler call
10d80 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
10d90 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
10da0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10db0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
10dc0 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
10dd0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49  ocking event.  I
10de0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
10df0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
10e00 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
10e10 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
10e20 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
10e30 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
10e40 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
10e50 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
10e60 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
10e70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
10e80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
10e90 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
10ea0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
10eb0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
10ec0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
10ed0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
10ee0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
10ef0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
10f00 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
10f10 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
10f20 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
10f30 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
10f40 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
10f50 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
10f60 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69  tention. If SQLi
10f70 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
10f80 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
10f90 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
10fa0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
10fb0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
10fc0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
10fd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10fe0 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
10ff0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
11000 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
11010 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
11020 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
11030 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
11040 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
11050 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
11060 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
11070 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
11080 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
11090 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
110a0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
110b0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
110c0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
110d0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
110e0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
110f0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
11100 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
11110 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
11120 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
11130 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
11140 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
11150 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
11160 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
11170 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
11180 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
11190 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
111a0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
111b0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
111c0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
111d0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
111e0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
111f0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
11200 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
11210 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
11220 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
11230 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
11240 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
11250 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
11260 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
11270 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
11280 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
11290 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
112a0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
112b0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
112c0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
112d0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
112e0 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
112f0 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
11300 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
11310 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
11320 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
11330 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
11340 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
11350 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
11360 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
11370 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
11380 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
11390 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
113a0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
113b0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
113c0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
113d0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
113e0 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
113f0 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
11400 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
11410 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
11420 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
11430 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
11440 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
11450 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
11460 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
11470 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
11480 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
11490 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
114a0 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
114b0 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
114c0 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
114d0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
114e0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
114f0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
11500 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
11510 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
11520 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
11530 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
11540 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
11550 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
11560 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
11570 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
11580 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
11590 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
115a0 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
115b0 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
115c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
115d0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
115e0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
115f0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
11600 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
11610 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
11620 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
11630 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
11640 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
11650 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
11660 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
11670 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11680 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
11690 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
116a0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
116b0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
116c0 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65  t handler.  Note
116d0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
116e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
116f0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
11700 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
11710 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11720 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  r..**.** INVARIA
11730 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  NTS:.**.** {H123
11740 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
11750 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
11760 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  C,A)] function s
11770 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20  hall replace.** 
11780 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63 61           busy ca
11790 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64  llback in the [d
117a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
117b0 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77  on] D with a new
117c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e  .**          a n
117d0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
117e0 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  C and applicatio
117f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41  n data pointer A
11800 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d  ..**.** {H12312}
11810 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b   Newly created [
11820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11830 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65  ions] shall have
11840 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20   a busy.**      
11850 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e      handler of N
11860 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ULL..**.** {H123
11870 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
11880 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 63  more [database c
11890 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72  onnections] shar
118a0 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e a.**          
118b0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
118c0 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63  shared_cache | c
118d0 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a  ommon cache],.**
118e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75            the bu
118f0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
11900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11910 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79  ection currently
11920 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
11930 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68 61     the cache sha
11940 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ll be invoked wh
11950 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63  en the cache enc
11960 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a  ounters a lock..
11970 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49  **.** {H12316} I
11980 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
11990 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
119a0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  s zero, then the
119b0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
119c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
119d0 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
119e0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68  locking event sh
119f0 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
11a00 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
11a10 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20  {H12318} SQLite 
11a20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68  shall invokes th
11a30 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  e busy handler w
11a40 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
11a50 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  s which.**      
11a60 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f      are a copy o
11a70 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75  f the pointer su
11a80 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72  pplied by the 3r
11a90 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
11aa0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
11ab0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11ac0 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20  ()] and a count 
11ad0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
11ae0 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
11af0 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f     invocations o
11b00 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  f the busy handl
11b10 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  er for the same 
11b20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a  locking event..*
11b30 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
11b40 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d  :.**.** {A12319}
11b50 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
11b60 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
11b70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11b80 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11b90 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20     or [prepared 
11ba0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
11bb0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
11bc0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
11bd0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
11be0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
11bf0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
11c00 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
11c10 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
11c20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b  A Busy Timeout {
11c30 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e  H12340} <S40410>
11c40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
11c50 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
11c60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11c70 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
11c80 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
11c90 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
11ca0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
11cb0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
11cc0 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
11cd0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
11ce0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
11cf0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
11d00 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11d10 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
11d20 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
11d30 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65  d. {H12343} Afte
11d40 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  r "ms" milliseco
11d50 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
11d60 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
11d70 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
11d80 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
11d90 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
11da0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
11db0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
11dc0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
11dd0 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
11de0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
11df0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
11e00 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
11e10 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
11e20 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
11e30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
11e40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
11e50 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
11e60 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
11e70 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
11e90 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
11ea0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
11eb0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
11ec0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
11ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
11ee0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
11ef0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
11f00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
11f10 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
11f20 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
11f30 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
11f40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  NTS:.**.** {H123
11f50 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11f60 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
11f70 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
11f80 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 69  override any pri
11f90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
11fa0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
11fb0 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eout()] or [sqli
11fc0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11fd0 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20  ()] setting.**  
11fe0 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
11ff0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
12000 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
12010 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 65   {H12343} If the
12020 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
12030 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
12040 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65  timeout()] is le
12050 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  ss than.**      
12060 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20      or equal to 
12070 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62  zero, then the b
12080 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
12090 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20  l be cleared so 
120a0 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
120b0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
120c0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
120d0 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
120e0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
120f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20  .**.** {H12344} 
12100 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
12110 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
12120 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
12130 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
12140 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
12150 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
12160 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62   handler shall b
12170 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61  e set that repea
12180 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20  tedly calls.**  
12190 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65          the xSle
121a0 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74  ep() method in t
121b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
121c0 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d  | VFS interface]
121d0 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20   until.**       
121e0 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f     either the lo
121f0 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74  ck clears or unt
12200 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76  il the cumulativ
12210 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20  e sleep time.** 
12220 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 65           reporte
12230 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70  d back by xSleep
12240 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c  () exceeds N mil
12250 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e  liseconds..*/.in
12260 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
12270 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
12280 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
12290 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
122a0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
122b0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
122c0 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31  ies {H12370} <S1
122d0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  0000>.**.** Defi
122e0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
122f0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
12300 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
12310 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
12320 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
12330 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
12340 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
12350 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
12360 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
12370 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
12380 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
12390 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
123a0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
123b0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
123c0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
123d0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
123e0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
123f0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
12400 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12410 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
12420 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
12430 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
12440 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
12450 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
12460 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
12470 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
12480 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
12490 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
124a0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
124b0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
124c0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
124d0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
124e0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
124f0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
12500 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
12510 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
12520 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
12530 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
12540 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
12550 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
12560 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
12570 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
12580 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
12590 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
125a0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
125b0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
125c0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
125d0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
125e0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
125f0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
12600 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
12610 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
12630 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
12640 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
12650 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
12660 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
12670 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
12680 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
12690 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
126a0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
126b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
126c0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
126d0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
126e0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
126f0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
12700 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
12710 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
12720 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
12730 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
12740 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
12750 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
12760 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12770 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
12780 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
12790 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
127a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
127b0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
127c0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
127d0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
127e0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
127f0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
12800 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
12810 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12820 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
12830 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
12840 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
12850 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
12860 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
12870 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
12880 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
12890 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
128a0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
128b0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
128c0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
128d0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
128e0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
128f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12900 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12910 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
12920 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12930 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
12940 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
12950 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
12960 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
12970 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12980 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
12990 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
129a0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
129b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
129c0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
129d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
129e0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
129f0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
12a00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
12a10 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
12a20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12a30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12a40 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
12a50 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
12a60 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
12a70 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
12a80 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
12a90 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
12aa0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
12ab0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
12ac0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
12ad0 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
12ae0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
12af0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
12b00 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
12b10 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
12b20 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
12b30 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
12b40 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
12b50 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
12b60 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f  d.** pass the po
12b70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
12b80 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
12b90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12ba0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
12bb0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
12bc0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
12bd0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
12be0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
12bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12c00 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
12c10 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
12c20 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
12c30 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
12c40 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
12c50 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
12c60 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
12c70 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
12c80 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
12c90 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
12ca0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
12cb0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
12cc0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
12cd0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12ce0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
12cf0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
12d00 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
12d10 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
12d20 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
12d30 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
12d40 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
12d50 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
12d60 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
12d70 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
12d80 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
12d90 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
12da0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
12db0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
12dc0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
12dd0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
12de0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
12df0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
12e00 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
12e10 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
12e20 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
12e30 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
12e40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
12e50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
12e60 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ode()] or [sqlit
12e70 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
12e80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
12e90 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49  **.** {H12371} I
12ea0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  f a [sqlite3_get
12eb0 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20  _table()] fails 
12ec0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
12ed0 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ion, then.**    
12ee0 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66        it shall f
12ef0 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ree the result t
12f00 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74  able under const
12f10 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74  ruction, abort t
12f20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71  he.**          q
12f30 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c  uery in process,
12f40 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71   skip any subseq
12f50 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
12f60 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
12f70 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74    *pazResult out
12f80 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  put pointer to N
12f90 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ULL and return [
12fa0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
12fb0 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66  *.** {H12373} If
12fc0 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61   the pnColumn pa
12fd0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
12fe0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12ff0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
13000 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
13010 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
13020 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
13030 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
13040 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
13050 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65   write the numbe
13060 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
13070 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
13080 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
13090 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e  e query into *pn
130a0 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  Column..**.** {H
130b0 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e  12374} If the pn
130c0 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f  Row parameter to
130d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
130e0 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55  ble()] is not NU
130f0 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
13100 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c  hen a successful
13110 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13120 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13130 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  e()] shall.**   
13140 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74 68         writes th
13150 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
13160 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
13170 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
13180 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
13190 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b   *pnRow..**.** {
131a0 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65 73  H12376} A succes
131b0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
131c0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
131d0 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f  table()] that co
131e0 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20  mputes.**       
131f0 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73     N rows of res
13200 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d  ult with C colum
13210 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c  ns per row shall
13220 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74   make *pazResult
13230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
13240 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  nt to an array o
13250 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e  f pointers to (N
13260 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68  +1)*C strings wh
13270 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ere the first.**
13280 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72 69            C stri
13290 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e  ngs are column n
132a0 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64  ames as obtained
132b0 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
132c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
132d0 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68  n_name()] and th
132e0 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d  e rest are colum
132f0 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a  n result values.
13300 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61  **          obta
13310 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
13320 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
13330 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39  ]..**.** {H12379
13340 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20  } The values in 
13350 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72  the pazResult ar
13360 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ray returned by 
13370 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
13380 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
13390 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76    shall remain v
133a0 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72  alid until clear
133b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
133c0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
133d0 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65  .** {H12382} Whe
133e0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
133f0 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74  s during evaluat
13400 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
13410 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20  get_table()].** 
13420 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
13430 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
13440 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55  *pazResult to NU
13450 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72  LL, write an err
13460 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
13470 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f         into memo
13480 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
13490 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
134a0 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20  ()], make.**    
134b0 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67        **pzErrmsg
134c0 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65   point to that e
134d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e  rror message, an
134e0 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20  d return a.**   
134f0 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61         appropria
13500 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
13510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
13520 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
13530 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
13540 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
13550 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
13560 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
13570 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
13580 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
13590 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
135a0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
135b0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
135c0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
135d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
135e0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
135f0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
13600 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
13610 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
13620 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
13630 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
13640 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
13650 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
13660 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
13670 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
13680 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
13690 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
136a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
136b0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
136c0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
136d0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
136e0 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
136f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
13700 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
13710 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
13720 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
13730 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
13740 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
13750 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
13760 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
13770 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
13780 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
13790 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
137a0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
137b0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
137c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
137d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
137e0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
137f0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
13800 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
13810 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
13820 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
13830 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75  ee()].  Both rou
13840 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
13850 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
13860 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
13870 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
13880 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
13890 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
138a0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
138b0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
138c0 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
138d0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
138e0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
138f0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
13900 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
13910 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
13920 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
13930 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
13940 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
13950 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13960 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
13970 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
13980 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13990 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
139a0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
139b0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
139c0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
139d0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
139e0 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
139f0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
13a00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
13a10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
13a20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
13a30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
13a40 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
13a50 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
13a60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
13a70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
13a80 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
13a90 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
13aa0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
13ab0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
13ac0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
13ad0 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
13ae0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
13af0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
13b00 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
13b10 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
13b20 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
13b30 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
13b40 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
13b50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
13b60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
13b70 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
13b80 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
13b90 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
13ba0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
13bb0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
13bc0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
13bd0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
13be0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
13bf0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
13c00 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
13c10 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
13c20 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
13c30 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
13c40 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
13c50 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
13c60 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
13c70 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
13c80 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
13c90 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
13ca0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
13cb0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
13cc0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
13cd0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
13ce0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
13cf0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
13d00 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
13d10 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
13d20 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
13d30 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
13d40 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
13d50 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
13d60 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
13d70 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
13d80 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
13d90 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
13da0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
13db0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
13dc0 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
13dd0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
13de0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
13df0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
13e00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
13e10 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
13e20 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
13e30 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
13e40 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
13e50 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
13e60 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
13e70 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
13e80 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
13e90 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
13ea0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
13eb0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
13ec0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
13ed0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
13ee0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
13ef0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
13f00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
13f10 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
13f20 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
13f30 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
13f40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
13f50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13f60 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
13f70 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
13f80 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
13f90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
13fa0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
13fb0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
13fc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
13fd0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
13fe0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13ff0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
14000 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
14010 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
14020 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
14030 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
14040 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
14050 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
14060 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
14070 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
14080 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14090 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
140a0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
140b0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
140c0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
140d0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
140e0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
140f0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
14100 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
14110 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
14120 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
14130 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
14140 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
14150 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
14160 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14170 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
14180 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
14190 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
141a0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
141b0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
141c0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
141d0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
141e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
141f0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
14200 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
14210 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
14220 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
14230 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
14240 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
14250 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
14260 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
14270 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
14280 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
14290 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
142a0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
142b0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
142c0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
142d0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51  al..**.** The %Q
142e0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
142f0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
14300 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
14310 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
14320 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
14330 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
14340 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
14350 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
14360 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
14370 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
14380 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
14390 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
143a0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
143b0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
143c0 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
143d0 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
143e0 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  n.  So, for exam
143f0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
14400 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
14410 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14420 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
14430 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
14440 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
14450 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
14460 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
14470 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
14480 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
14490 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
144a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
144b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
144c0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
144d0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
144e0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
144f0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
14500 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
14510 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
14520 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
14530 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
14540 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
14550 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
14560 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
14570 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
14580 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
14590 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
145a0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
145b0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
145c0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
145d0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
145e0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
145f0 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
14600 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14610 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20  .**.** {H17403} 
14620 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70   The [sqlite3_mp
14630 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71  rintf()] and [sq
14640 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
14650 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
14660 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
14670 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73   either pointers
14680 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
14690 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
146a0 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20  s held in.**    
146b0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62         memory ob
146c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
146d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
146e0 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
146f0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
14700 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
14710 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69  e3_malloc()] fai
14720 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  ls..**.** {H1740
14730 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  6}  The [sqlite3
14740 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
14750 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20  erface writes a 
14760 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
14770 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46  **           UTF
14780 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74  -8 string into t
14790 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65  he buffer pointe
147a0 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  d to by the seco
147b0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
147c0 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64            provid
147d0 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73  ed that the firs
147e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67  t parameter is g
147f0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
14800 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d  ..**.** {H17407}
14810 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
14820 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
14830 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72  face does not wr
14840 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20  ite slots of.** 
14850 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75            its ou
14860 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65  tput buffer (the
14870 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14880 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72  r) outside the r
14890 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
148a0 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e    of 0 through N
148b0 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74  -1 (where N is t
148c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
148d0 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er).**          
148e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
148f0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
14900 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
14910 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62       requested b
14920 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
14930 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63  cification..*/.c
14940 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
14950 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
14960 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
14970 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
14980 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
14990 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
149a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
149b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
149c0 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
149d0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
149e0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
149f0 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c  ystem {H17300} <
14a00 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20000>.**.** Th
14a10 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75  e SQLite core  u
14a20 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
14a30 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
14a40 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
14a50 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
14a60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14a70 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
14a80 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
14a90 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
14aa0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
14ab0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
14ac0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
14ad0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
14ae0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
14af0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
14b00 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
14b10 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
14b20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61  * The sqlite3_ma
14b30 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
14b40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14b50 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
14b60 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
14b70 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
14b80 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
14b90 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
14ba0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
14bb0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
14bc0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
14bd0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
14be0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
14bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
14c00 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
14c10 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
14c20 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
14c30 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
14c40 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
14c50 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
14c60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
14c70 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71  **.** Calling sq
14c80 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
14c90 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
14ca0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
14cb0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
14cc0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
14cd0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
14ce0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
14cf0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
14d00 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
14d10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65   The sqlite3_fre
14d20 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
14d30 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
14d40 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
14d50 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
14d60 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
14d70 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
14d80 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
14d90 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
14da0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
14db0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
14dc0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
14dd0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
14de0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
14df0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
14e00 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
14e10 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14e20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
14e30 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
14e40 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
14e50 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
14e60 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
14e70 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
14e80 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
14e90 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
14ea0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
14eb0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
14ec0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
14ed0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
14ee0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14ef0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65  ) or sqlite3_fre
14f00 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  e()..**.** The s
14f10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14f20 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
14f30 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
14f40 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
14f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
14f60 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14f70 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
14f80 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
14f90 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
14fa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14fb0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
14fc0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
14fd0 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66  meter.  If the f
14fe0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14ff0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15000 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
15010 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
15020 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
15030 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
15040 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
15050 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
15060 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
15070 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15080 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15090 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
150a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
150b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
150c0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
150d0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
150e0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
150f0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
15100 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
15110 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
15120 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
15130 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15140 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15160 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
15170 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
15180 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
15190 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
151a0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
151b0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
151c0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
151d0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20  ilable..** If M 
151e0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
151f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15200 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
15210 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
15220 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15230 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
15240 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
15250 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
15260 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
15270 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
15280 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
15290 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
152a0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65  ** If sqlite3_re
152b0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
152c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
152d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
152e0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
152f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
15300 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
15310 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
15320 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
15330 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
15340 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
15350 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
15360 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
15370 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
15380 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
15390 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
153a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
153b0 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20  tem uses.** the 
153c0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
153d0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70  c() and free() p
153e0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73  rovided by the s
153f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
15400 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48  y..** {H17382} H
15410 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
15420 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15430 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
15440 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e  _MEMORY_SIZE=<i>
15450 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f  NNN</i> C prepro
15460 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68  cessor macro (wh
15470 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a  ere <i>NNN</i>.*
15480 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29  * is an integer)
15490 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
154a0 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72  eate a static ar
154b0 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a  ray of at least.
154c0 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  ** <i>NNN</i> by
154d0 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
154e0 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20  uses that array 
154f0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
15500 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79  ynamic.** memory
15510 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15520 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69  s. {END}  Additi
15530 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  onal memory allo
15540 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a  cator options.**
15550 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
15560 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
15570 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
15580 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
15590 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
155a0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
155b0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
155c0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
155d0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
155e0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
155f0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
15600 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
15610 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
15620 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
15630 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
15640 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
15650 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
15660 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
15670 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
15680 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
15690 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
156a0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
156b0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
156c0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
156d0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
156e0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
156f0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
15700 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
15710 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
15720 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
15730 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
15740 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
15750 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
15760 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
15770 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
15780 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
15790 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
157a0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
157b0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
157c0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
157d0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
157e0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
157f0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
15800 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
15810 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
15820 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
15830 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
15840 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
15850 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20  ither a pointer 
15860 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
15870 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d  a newly checked-
15880 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20  out block of at 
15890 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66  least N bytes of
158a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
158b0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
158c0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
158d0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  it returns NULL 
158e0 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a  if it is unable.
158f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
15900 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75  fulfill the requ
15910 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  est..**.** {H173
15920 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  04}  The [sqlite
15930 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
15940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
15950 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
15960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20  .**           N 
15970 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
15980 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a  equal to zero..*
15990 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54  *.** {H17305}  T
159a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  he [sqlite3_free
159b0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (P)] interface r
159c0 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70  eleases memory p
159d0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
159e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
159f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
15a00 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
15a10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
15a20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b  **           mak
15a30 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65  ing it available
15a40 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a   for reuse..**.*
15a50 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61  * {H17306}  A ca
15a60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
15a70 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20  ree(NULL)] is a 
15a80 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
15a90 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20  **.** {H17310}  
15aa0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
15ab0 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d  e3_realloc(0,N)]
15ac0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
15ad0 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
15ae0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
15af0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a  3_malloc(N)]..**
15b00 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20  .** {H17312}  A 
15b10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
15b20 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69  _realloc(P,0)] i
15b30 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
15b40 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
15b50 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
15b60 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20  free(P)]..**.** 
15b70 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20 53 51  {H17315}  The SQ
15b80 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b  Lite core uses [
15b90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15ba0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  ], [sqlite3_real
15bb0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
15bc0 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65       and [sqlite
15bd0 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c  3_free()] for al
15be0 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20  l of its memory 
15bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a  allocation and.*
15c00 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c  *           deal
15c10 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15c20 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20  **.** {H17318}  
15c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  The [sqlite3_rea
15c40 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72  lloc(P,N)] inter
15c50 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
15c60 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  her a pointer.**
15c70 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20             to a 
15c80 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64  block of checked
15c90 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61  -out memory of a
15ca0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
15cb0 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20  in size.**      
15cc0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
15cd0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
15ce0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
15cf0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20  **.** {H17321}  
15d00 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
15d10 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
15d20 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
15d30 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
15d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
15d50 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b  pies the first K
15d60 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e   bytes of conten
15d70 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68  t from P into th
15d80 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20  e newly.**      
15d90 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
15da0 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73  lock, where K is
15db0 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e   the lesser of N
15dc0 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66   and the size of
15dd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
15de0 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
15df0 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e  * {H17322}  When
15e00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15e10 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
15e20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
15e30 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20  er, it first.** 
15e40 20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61 73            releas
15e50 65 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e  es the buffer P.
15e60 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20  .**.** {H17323} 
15e70 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   When [sqlite3_r
15e80 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74  ealloc(P,N)] ret
15e90 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62  urns NULL, the b
15ea0 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20  uffer P is.**   
15eb0 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69          not modi
15ec0 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64  fied or released
15ed0 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
15ee0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33  ONS:.**.** {A173
15ef0 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72  50}  The pointer
15f00 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
15f10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
15f20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
15f30 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  loc()].**       
15f40 20 20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68      must be eith
15f50 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
15f60 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
15f70 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
15f80 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  *           invo
15f90 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15fa0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
15fb0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15fc0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
15fd0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79             not y
15fe0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
15ff0 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d  ..**.** {A17351}
16000 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
16010 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
16020 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
16030 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  t of.**         
16040 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d    a block of mem
16050 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
16060 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
16070 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
16080 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28    [sqlite3_free(
16090 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
160a0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
160b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
160c0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
160d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
160e0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
160f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
16100 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16110 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
16120 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
16130 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30  cs {H17370} <S30
16140 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  210>.**.** SQLit
16150 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
16160 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
16170 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
16180 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
16190 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
161a0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
161b0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
161c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
161d0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
161e0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
161f0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16200 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
16210 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  stem..**.** INVA
16220 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
16230 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
16240 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16250 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
16260 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16270 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
16280 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72     of memory cur
16290 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
162a0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
162b0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a   not freed)..**.
162c0 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20  ** {H17373} The 
162d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
162e0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
162f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
16300 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20   maximum.**     
16310 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73       value of [s
16320 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16330 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
16340 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
16350 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
16360 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a  last reset..**.*
16370 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76  * {H17374} The v
16380 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
16390 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
163a0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
163b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
163c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
163d0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
163e0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20  ny overhead.**  
163f0 20 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79          added by
16400 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
16410 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
16420 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16430 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
16440 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
16450 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
16460 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
16470 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
16480 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
16490 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
164a0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
164b0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  ll..**.** {H1737
164c0 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  5} The memory hi
164d0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
164e0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
164f0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
16500 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16510 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16520 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
16530 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
16540 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
16550 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16560 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
16570 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20  rue.  The value 
16580 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
16590 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
165a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
165b0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
165c0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
165d0 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74           prior t
165e0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
165f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16600 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16610 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
16620 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
16630 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
16640 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
16650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16660 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
16670 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
16680 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30  {H17390} <S20000
16690 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
166a0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
166b0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
166c0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
166d0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
166e0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
166f0 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65  andom ROWIDs whe
16700 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
16710 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
16720 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
16730 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
16740 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52  rgest possible R
16750 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20  OWID.  The PRNG 
16760 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
16770 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
16780 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
16790 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
167a0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
167b0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
167c0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
167d0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
167e0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
167f0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
16800 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
16810 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
16820 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
16830 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
16840 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
16850 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
16860 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
16870 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
16880 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
16890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
168a0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
168b0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
168c0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
168d0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
168e0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
168f0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
16900 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
16910 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
16920 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
16930 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
16940 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
16950 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
16960 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
16970 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
16980 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
16990 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
169a0 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
169b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
169c0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
169d0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
169e0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
169f0 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
16a00 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
16a10 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
16a20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
16a30 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
16a40 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
16a50 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
16a60 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
16a70 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
16a80 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
16a90 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
16aa0 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
16ab0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
16ac0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
16ad0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16ae0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
16af0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
16b00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
16b10 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
16b20 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
16b30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
16b40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16b50 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
16b60 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
16b70 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
16b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
16b90 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
16ba0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
16bb0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
16bc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
16bd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16be0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
16bf0 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
16c00 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
16c10 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
16c20 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
16c30 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
16c40 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
16c50 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
16c60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16c70 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16c80 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
16c90 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
16ca0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
16cb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16cc0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
16cd0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
16ce0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
16cf0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
16d00 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
16d10 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
16d20 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
16d30 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
16d40 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
16d50 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
16d60 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
16d70 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
16d80 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
16d90 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
16da0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
16db0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
16dc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16dd0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
16de0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
16df0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
16e00 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
16e10 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16e20 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
16e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16e40 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16e50 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
16e60 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
16e70 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
16e80 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
16e90 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
16ea0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
16eb0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
16ec0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
16ed0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
16ee0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
16ef0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
16f00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16f10 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
16f20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
16f30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16f40 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
16f50 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
16f60 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
16f70 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
16f80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
16f90 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
16fa0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
16fb0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
16fc0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
16fd0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
16fe0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
16ff0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
17000 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
17010 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
17020 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
17030 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
17040 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
17050 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
17060 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
17070 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
17080 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
17090 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
170a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
170b0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
170c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
170d0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
170e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
170f0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
17100 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
17110 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
17120 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
17130 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
17140 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17150 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17160 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
17170 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
17180 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17190 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
171a0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
171b0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
171c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
171d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
171e0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
171f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
17200 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
17210 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
17220 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
17230 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
17240 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
17250 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
17260 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
17270 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
17280 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
17290 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
172a0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
172b0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
172c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
172d0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
172e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
172f0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
17300 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
17310 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
17320 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
17330 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
17340 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
17350 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
17360 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
17370 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
17380 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
17390 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
173a0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
173b0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
173c0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
173d0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
173e0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
173f0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
17400 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
17410 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
17420 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
17430 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
17440 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
17450 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
17460 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
17470 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
17480 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
17490 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
174a0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
174b0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
174c0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
174d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
174e0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
174f0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
17500 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
17510 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
17520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
17530 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
17540 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
17550 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
17560 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
17570 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
17580 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
17590 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
175a0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
175b0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
175c0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
175d0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
175e0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
175f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
17600 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
17610 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
17620 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
17630 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
17640 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
17650 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
17660 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
17670 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
17680 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
17690 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
176a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
176b0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
176c0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
176d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
176e0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
176f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
17700 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
17710 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
17720 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
17730 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
17740 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
17750 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
17760 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  lt..**.** Note t
17770 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
17780 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
17790 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
177a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
177b0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
177c0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
177d0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
177e0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
177f0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
17800 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
17810 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
17820 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17830 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
17840 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
17850 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
17860 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
17870 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
17880 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
17890 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
178a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
178b0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
178c0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
178d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
178e0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
178f0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
17900 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
17910 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
17920 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65 20  {H12503} If the 
17930 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17940 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ack returns any 
17950 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
17970 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
17980 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
17990 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
179a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
179b0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
179c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
179d0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
179e0 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20   caused.**      
179f0 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a      the authoriz
17a00 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
17a10 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  un shall fail wi
17a20 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
17a30 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
17a40 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
17a50 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
17a60 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
17a70 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65  .** {H12504} Whe
17a80 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
17a90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17aa0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
17ab0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17ac0 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62           describ
17ad0 65 64 20 69 73 20 70 72 6f 63 65 73 73 65 64 20  ed is processed 
17ae0 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  normally..**.** 
17af0 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68  {H12505} When th
17b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17b10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
17b20 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
17b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17b40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17b50 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
17b60 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
17b70 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
17b80 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
17b90 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
17ba0 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20  all fail.**     
17bb0 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51       with an [SQ
17bc0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
17bd0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72  r code and an er
17be0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
17bf0 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69          explaini
17c00 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69  ng that access i
17c10 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  s denied..**.** 
17c20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20  {H12506} If the 
17c30 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
17c40 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
17c50 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
17c60 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
17c70 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53   callback) is [S
17c80 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20  QLITE_READ] and 
17c90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17ca0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
17cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
17cc0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65  ITE_IGNORE], the
17cd0 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
17ce0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
17cf0 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20  tructed to.**   
17d00 20 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20         insert a 
17d10 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17d20 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17d30 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17d40 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  ld have.**      
17d50 20 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66      been read if
17d60 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
17d70 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a   been returned..
17d80 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49  **.** {H12507} I
17d90 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
17da0 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
17db0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17dc0 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
17dd0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
17de0 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68   is anything oth
17df0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
17e00 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  READ], then.**  
17e10 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
17e20 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f   of [SQLITE_IGNO
17e30 52 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65  RE] has the same
17e40 20 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49   effect as [SQLI
17e50 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DENY]..**.** 
17e60 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72  {H12510} The fir
17e70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17e80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17e90 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17ea0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
17eb0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
17ec0 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
17ed0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17ee0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
17ef0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d  ..**.** {H12511}
17f00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17f10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
17f20 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
17f30 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
17f40 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17f50 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17f60 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
17f70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
17f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
17f90 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
17fa0 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68  *.** {H12512} Th
17fb0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
17fc0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
17fd0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
17fe0 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
17ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18000 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
18010 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ntain.**        
18020 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
18030 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
18040 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
18050 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
18060 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
18070 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
18080 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
18090 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20  verrides.**     
180a0 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75       any previou
180b0 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75  sly installed au
180c0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
180d0 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20  {H12521} A NULL 
180e0 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
180f0 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
18100 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  zation.**       
18110 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69     callback is i
18120 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
18130 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75  12522} The defau
18140 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  lt authorizer is
18150 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
18160 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18170 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18180 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18190 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
181a0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
181b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
181c0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
181d0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
181e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
181f0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
18200 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  turn Codes {H125
18210 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  90} <H12500>.**.
18220 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
18230 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18250 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
18260 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
18270 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
18280 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
18290 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
182a0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
182b0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
182c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
182d0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
182e0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
182f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18300 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
18310 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
18320 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
18330 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
18340 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
18350 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
18360 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
18370 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
18380 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
18390 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
183a0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
183b0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
183c0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
183d0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
183e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
183f0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
18400 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48  odes {H12550} <H
18410 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
18420 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18430 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
18440 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
18450 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18460 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
18470 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
18480 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
18490 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
184a0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
184b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
184c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
184d0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
184e0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
184f0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
18500 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
18510 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
18520 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
18530 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
18540 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18550 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
18560 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
18570 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
18580 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
18590 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
185a0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
185b0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
185c0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
185d0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
185e0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
185f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18600 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
18610 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
18620 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
18630 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
18640 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
18650 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18660 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
18670 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
18680 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18690 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
186a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
186b0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
186c0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
186d0 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
186e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
186f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18700 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
18710 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
18720 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
18730 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18740 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
18750 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
18760 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
18770 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
18780 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
18790 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
187a0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
187b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
187c0 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65  .** {H12551} The
187d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
187e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20  r to an.**      
187f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
18800 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18820 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20  k] is always an 
18830 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
18840 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
18850 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
18860 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
18870 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a  es what action.*
18880 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65  *          is be
18890 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a  ing authorized..
188a0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54  **.** {H12552} T
188b0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
188c0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
188d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
188e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
188f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61  izer | authoriza
18900 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a  tion callback].*
18910 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
18920 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
18930 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
18940 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  on which.**     
18950 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
18960 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
18970 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
18980 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18990 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
189a0 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
189b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
189c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
189d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
189e0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
189f0 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
18a00 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
18a10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18a20 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
18a30 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
18a40 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
18a50 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54  **.** {H12554} T
18a60 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
18a70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
18a80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
18a90 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18aa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18ab0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
18ac0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
18ad0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
18ae0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
18af0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
18b00 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
18b10 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18b20 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18b30 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18b40 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18b50 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
18b60 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
18b70 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
18b80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18b90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18ba0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
18bb0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
18bc0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
18bd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
18be0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
18bf0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18c00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c20 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
18c30 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
18c40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18c50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c70 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
18c80 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
18c90 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18ca0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18cc0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
18cd0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
18ce0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18cf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d10 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
18d20 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
18d30 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18d40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d60 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
18d70 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
18d80 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18d90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18db0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
18dc0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
18dd0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18de0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18e00 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
18e10 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
18e20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18e30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
18e50 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
18e60 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
18e70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18e80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18ea0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
18eb0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
18ec0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18ed0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18ef0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
18f00 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
18f10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18f20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18f30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18f40 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
18f50 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
18f60 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18f70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18f80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
18f90 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
18fa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18fb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18fc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18fd0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
18fe0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
18ff0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19000 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19020 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
19030 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
19040 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19050 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19070 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
19080 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
19090 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
190a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
190b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
190c0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
190d0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
190e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
190f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19110 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
19120 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
19130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19140 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19160 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
19170 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
19180 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
19190 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
191a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
191b0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
191c0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
191d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
191e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
191f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19200 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
19210 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
19220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
19230 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19250 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
19260 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
19270 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
19280 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
192a0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
192b0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
192c0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
192d0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
192e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
192f0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
19300 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
19310 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
19320 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
19340 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
19350 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
19360 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
19370 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19380 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
19390 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
193a0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
193b0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
193c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
193d0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
193e0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
193f0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
19400 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19410 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19420 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
19430 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
19440 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
19450 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19460 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19470 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19480 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
19490 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
194a0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
194b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
194c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
194d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
194e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
194f0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
19500 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19510 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
19520 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
19530 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
19540 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
19550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19560 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
19570 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
19580 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
19590 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
195a0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
195b0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
195c0 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c  tions {H12280} <
195d0 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60400>.** EXPER
195e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
195f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
19600 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
19610 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
19620 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
19630 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
19640 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
19650 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
19660 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
19670 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19680 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19690 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
196a0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
196b0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
196c0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
196d0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
196e0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
196f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
19700 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19710 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19720 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
19730 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
19740 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19750 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19760 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
19770 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
19780 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
19790 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
197a0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
197b0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
197c0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
197d0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
197e0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
197f0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
19800 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  trigger..**.** T
19810 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19820 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19830 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
19840 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19850 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19860 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19870 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
19880 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
19890 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
198a0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
198b0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
198c0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
198d0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
198e0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
198f0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
19900 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19910 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20  .**.** {H12281} 
19920 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19930 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
19940 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   by [sqlite3_tra
19950 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  ce()] is.**     
19960 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
19970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
19980 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
19990 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
199a0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
199b0 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
199c0 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
199d0 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
199e0 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {H12282} Each ca
199f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
19a00 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65  race()] override
19a10 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79  s the previously
19a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
19a30 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61  istered trace ca
19a40 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  llback..**.** {H
19a50 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72  12283} A NULL tr
19a60 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73  ace callback dis
19a70 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a  ables tracing..*
19a80 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68  *.** {H12284} Th
19a90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19aa0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
19ab0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
19ac0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
19ad0 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
19ae0 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
19af0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
19b00 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
19b10 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20  ** {H12285} The 
19b20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19b30 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
19b40 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
19b50 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
19b60 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
19b70 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
19b80 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
19b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
19ba0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19bb0 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
19bc0 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
19bd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
19be0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
19bf0 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
19c00 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
19c10 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
19c20 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
19c30 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
19c40 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
19c50 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65  .** {H12287} The
19c60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19c70 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
19c80 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
19c90 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
19ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
19cb0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
19cc0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
19cd0 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66  * {H12288} The f
19ce0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19cf0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
19d00 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
19d10 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
19d20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
19d30 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
19d40 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
19d50 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {H12289} The sec
19d60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
19d70 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
19d80 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
19d90 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
19da0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
19db0 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
19dc0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
19dd0 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
19de0 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
19df0 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
19e00 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
19e10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19e20 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
19e30 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
19e40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d  ..**.** {H12290}
19e50 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
19e60 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
19e70 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
19e80 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
19e90 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
19ea0 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
19eb0 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
19ec0 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
19ed0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
19ee0 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
19ef0 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
19f00 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76   to finish..*/.v
19f10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
19f20 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
19f30 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
19f40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
19f50 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
19f60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
19f70 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
19f80 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
19f90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
19fa0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
19fb0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19fc0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
19fd0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b  ress Callbacks {
19fe0 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e  H12910} <S60400>
19ff0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1a000 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
1a010 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a020 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
1a030 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
1a040 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1a050 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1a060 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
1a070 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
1a080 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1a090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a0a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1a0b0 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
1a0c0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1a0d0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1a0e0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1a0f0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1a100 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1a110 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
1a120 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1a130 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1a140 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1a150 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1a160 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1a170 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1a180 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1a190 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1a1a0 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
1a1b0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
1a1c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1a1d0 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
1a1e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1a1f0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1a200 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a210 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
1a220 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72    is invoked per
1a230 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1a240 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1a250 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
1a260 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
1a270 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ()]..**.** {H129
1a280 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  12} The progress
1a290 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1a2a0 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
1a2b0 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a  ery N virtual.**
1a2c0 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e            machin
1a2d0 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65  e opcodes, where
1a2e0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1a2f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a300 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
1a310 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1a320 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74  andler()] call t
1a330 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a  hat registered.*
1a340 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
1a350 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69  allback.  If N i
1a360 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73  s less than 1, s
1a370 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a380 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
1a390 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66        acts as if
1a3a0 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73   a NULL progress
1a3b0 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65   handler had bee
1a3c0 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a  n specified..**.
1a3d0 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20  ** {H12913} The 
1a3e0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1a3f0 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
1a400 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
1a410 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ird.**          
1a420 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1a430 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a440 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  dler()..**.** {H
1a450 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
1a460 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1a470 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1a480 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a  andler() is a.**
1a490 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70            void p
1a4a0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
1a4b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1a4c0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
1a4d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
1a4e0 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
1a4f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1a500 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
1a510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a520 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
1a530 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65  er than N opcode
1a540 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  s.**          be
1a550 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68  ing executed, th
1a560 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
1a570 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
1a580 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  r invoked..**.**
1a590 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72 79 20   {H12916} Every 
1a5a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a5b0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1a5c0 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  r()].**         
1a5d0 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20   overwrites any 
1a5e0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1a5f0 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 68  tered progress h
1a600 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  andler..**.** {H
1a610 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72  12917} If the pr
1a620 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1a630 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20  allback is NULL 
1a640 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73  then no progress
1a650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
1a660 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e  dler is invoked.
1a670 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20  .**.** {H12918} 
1a680 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1a690 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a6a0 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20   a result other 
1a6b0 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20  than 0, then.** 
1a6c0 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68           the beh
1a6d0 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73  avior is a if [s
1a6e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a6f0 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c  ()] had been cal
1a700 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  led..**         
1a710 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69   <S30500>.*/.voi
1a720 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1a730 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1a740 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1a750 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1a760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a770 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1a780 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1a790 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34  ion {H12700} <S4
1a7a0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0200>.**.** Thes
1a7b0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1a7c0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1a7d0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
1a7e0 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
1a7f0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
1a800 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c  rgument. The fil
1a810 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1a820 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1a830 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1a840 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a850 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a860 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1a870 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a880 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1a890 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a8a0 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63  ). A [database c
1a8b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1a8c0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1a8d0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1a8e0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1a8f0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1a900 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1a910 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1a920 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1a930 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1a940 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1a950 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1a960 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1a970 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1a980 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1a990 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1a9a0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1a9b0 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74  ject. If the dat
1a9c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a9d0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1a9e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1a9f0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1aa00 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1aa10 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1aa20 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1aa30 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  turned.  The.** 
1aa40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1aa50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1aa60 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1aa70 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1aa80 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1aa90 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1aaa0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1aab0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
1aac0 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
1aad0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1aae0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1aaf0 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1ab00 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1ab10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ab20 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1ab30 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1ab40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1ab50 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1ab60 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1ab70 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1ab80 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1ab90 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1aba0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1abb0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1abc0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1abd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1abe0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1abf0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1ac00 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1ac10 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1ac20 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1ac30 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1ac40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1ac50 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1ac60 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1ac70 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1ac80 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1ac90 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1aca0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1acb0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1acc0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1acd0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ace0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
1acf0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1ad00 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1ad10 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1ad20 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1ad30 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1ad40 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1ad50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1ad60 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a  UTEX] flag:.**.*
1ad70 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1ad80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1ad90 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1ada0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1adb0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1adc0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1add0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1ade0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1adf0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1ae00 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1ae10 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1ae20 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1ae30 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1ae40 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1ae50 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1ae60 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1ae70 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1ae80 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1ae90 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1aea0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1aeb0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1aec0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1aed0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1aee0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1aef0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1af00 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1af10 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1af20 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1af30 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1af40 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1af50 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1af60 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1af70 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1af80 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1af90 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1afa0 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1afb0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1afc0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1afd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1afe0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1aff0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1b000 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1b010 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1b020 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1b030 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1b040 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1b050 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1b060 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1b070 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1b080 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1b090 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1b0a0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1b0b0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1b0c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1b0d0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c  N_NOMUTEX] flag,
1b0e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1b0f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1b100 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  .**.** If the [S
1b110 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1b120 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1b130 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e   then mutexes on
1b140 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b   the.** opened [
1b150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b160 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65  ion] are disable
1b170 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61  d and the applia
1b180 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73  tion must.** ins
1b190 75 72 65 20 74 68 61 74 20 61 63 63 65 73 73 20  ure that access 
1b1a0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
1b1b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
1b1c0 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a   its associated.
1b1d0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1b1e0 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69  tements] is seri
1b1f0 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51  alized.  The [SQ
1b200 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b210 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68  X] flag.** is th
1b220 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1b230 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69 73 20  or is SQLite is 
1b240 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67  configured using
1b250 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1b260 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1b270 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1b280 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1b290 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74  AD] options.** t
1b2a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
1b2b0 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49  g()].  The [SQLI
1b2c0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1b2d0 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73   flag only makes
1b2e0 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65   a.** difference
1b2f0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
1b300 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b  in its default [
1b310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
1b320 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a  RIALIZED] mode..
1b330 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1b340 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1b350 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1b360 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1b370 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1b380 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1b390 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1b3a0 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
1b3b0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1b3c0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1b3d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b3e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1b3f0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1b400 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1b410 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1b420 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1b430 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1b440 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1b450 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1b460 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1b470 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1b480 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1b490 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1b4a0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1b4b0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1b4c0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1b4d0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1b4e0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1b4f0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1b500 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1b510 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
1b520 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1b530 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1b540 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1b550 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1b560 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1b570 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1b580 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1b590 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1b5a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1b5b0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1b5c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1b5d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b5e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
1b5f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1b600 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1b610 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1b620 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1b630 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1b640 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1b650 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1b660 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1b670 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1b680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b690 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
1b6a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1b6b0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1b6c0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1b6d0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b6e0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1b6f0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1b700 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1b710 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1b720 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1b730 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1b740 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1b750 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b760 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b770 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1b780 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1b790 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1b7a0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1b7b0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1b7c0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1b7d0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1b7e0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1b7f0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1b800 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1b810 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1b820 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1b830 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b840 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1b850 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1b860 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1b870 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1b880 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1b890 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1b8a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b8b0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
1b8c0 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
1b8d0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
1b8f0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
1b900 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
1b910 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
1b920 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
1b930 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1b940 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {H12702} The fil
1b950 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1b960 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1b970 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
1b980 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
1b990 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
1b9a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1b9b0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
1b9c0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
1b9d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1b9e0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
1b9f0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1ba00 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63   {H12703} A succ
1ba10 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1ba20 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
1ba30 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ba40 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1ba50 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1ba60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
1ba70 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
1ba80 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1ba90 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1baa0 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
1bab0 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ppDb..**.** {H12
1bac0 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
1bad0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1bae0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1baf0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1bb00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bb10 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
1bb20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1bb30 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1bb40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1bb50 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1bb60 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1bb70 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lure..**.** {H12
1bb80 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1bb90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1bba0 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1bbb0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1bbc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1bbd0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1bbe0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1bbf0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1bc00 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37  8..**.** {H12707
1bc10 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1bc20 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1bc30 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1bc40 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1bc50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1bc60 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1bc70 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1bc80 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b  * {H12709} The [
1bc90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1bca0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1bcb0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1bcc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1bcd0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1bce0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1bcf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1bd00 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1bd10 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1bd20 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1bd30 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  REATE]..**.** {H
1bd40 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1bd50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1bd60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1bd70 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1bd80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1bd90 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1bda0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1bdb0 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1bdc0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1bdd0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1bde0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1bdf0 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68  * {H12712} If th
1be00 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1be10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1be20 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1be30 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1be40 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1be50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1be60 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1be70 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1be80 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1be90 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1bea0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1beb0 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1bec0 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1bed0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1bee0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1bef0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1bf00 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  system..**.** {H
1bf10 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1bf20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1bf30 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
1bf40 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1bf50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1bf60 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1bf70 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1bf80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1bf90 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1bfa0 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1bfb0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1bfc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1bfd0 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65   {H12714} If the
1bfe0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1bff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1c000 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1c010 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1c020 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1c030 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1c040 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1c050 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1c060 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1c070 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1c080 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1c090 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1c0a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1c0b0 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1c0c0 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  base..**.** {H12
1c0d0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1c0e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1c0f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c100 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1c110 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1c120 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1c130 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1c140 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1c150 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1c160 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1c170 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1c180 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1c190 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1c1a0 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1c1b0 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1c1c0 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1c1d0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c1e0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1c1f0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1c200 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1c210 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39  o>.**.** {H12719
1c220 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1c230 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1c240 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1c250 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1c260 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1c270 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1c280 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1c290 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1c2a0 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1c2b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1c2c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1c2d0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1c2e0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1c2f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1c300 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1c310 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1c320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1c330 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1c340 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1c350 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1c360 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1c370 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c380 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1c390 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1c3a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1c3b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1c3c0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1c3d0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1c3e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c3f0 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {H12723} Two [da
1c400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c410 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1c420 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1c430 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1c440 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1c450 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1c460 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1c470 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1c480 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1c490 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1c4a0 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1c4b0 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1c4c0 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1c4d0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1c4e0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1c4f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1c500 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1c510 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1c520 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1c530 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1c540 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1c550 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1c560 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1c570 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1c580 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1c590 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1c5a0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1c5b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1c5c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1c5d0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c5e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c5f0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1c600 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1c610 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1c620 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1c630 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1c640 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1c650 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1c660 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1c670 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1c680 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1c690 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1c6a0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1c6b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1c6c0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1c6d0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1c6e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1c6f0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1c700 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1c710 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1c720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1c730 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1c740 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
1c750 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
1c760 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1c770 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1c780 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1c790 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1c7a0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1c7b0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1c7c0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1c7d0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1c7e0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1c7f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1c800 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c810 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1c820 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1c830 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1c840 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1c850 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1c860 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1c870 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1c880 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1c890 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
1c8a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1c8b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1c8c0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1c8d0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1c8e0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1c8f0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1c900 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1c910 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1c920 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
1c930 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c940 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1c950 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1c960 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1c970 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1c980 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1c990 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1c9a0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1c9b0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1c9c0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1c9d0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1c9e0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1c9f0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1ca00 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1ca10 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1ca20 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
1ca30 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1ca40 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1ca50 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1ca60 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1ca70 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1ca80 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1ca90 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1caa0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1cab0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1cac0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1cad0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1cae0 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  t be set..**.** 
1caf0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1cb00 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b  * {H12801} The [
1cb10 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cb20 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1cb30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1cb40 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72  c.**          [r
1cb50 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
1cb60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1cb70 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1cb80 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20  st recently.**  
1cb90 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69          failed i
1cba0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73  nterface call as
1cbb0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1cbc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1cbd0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
1cbe0 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73   {H12803} The [s
1cbf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29  qlite3_errmsg(D)
1cc00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1cc10 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20  rrmsg16(D)].**  
1cc20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1cc30 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  es return Englis
1cc40 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20  h-language text 
1cc50 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a  that describes.*
1cc60 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65  *          the e
1cc70 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74  rror in the most
1cc80 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c  ly recently fail
1cc90 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1cca0 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  l,.**          e
1ccb0 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72  ncoded as either
1ccc0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1ccd0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1cce0 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68  *.** {H12807} Th
1ccf0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1cd00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1cd10 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71  rrmsg()] and [sq
1cd20 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1cd30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1cd40 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
1cd50 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e  e next SQLite in
1cd60 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a  terface call..**
1cd70 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c  .** {H12808} Cal
1cd80 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
1cd90 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
1cda0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63  eturn an error c
1cdb0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
1cdc0 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
1cdd0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
1cde0 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  ) do not.**     
1cdf0 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20       change the 
1ce00 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65  error code or me
1ce10 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62  ssage returned b
1ce20 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1ce30 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1ce40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1ce50 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1ce60 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1ce70 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49  **.** {H12809} I
1ce80 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1ce90 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1cea0 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1ceb0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1cec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ced0 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1cee0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1cef0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1cf00 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1cf10 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1cf20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1cf30 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1cf40 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1cf50 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1cf60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cf70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1cf80 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1cf90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1cfa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cfb0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1cfc0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1cfd0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1cfe0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1cff0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1d000 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1d010 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d020 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1d030 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1d040 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1d050 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1d060 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1d070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d080 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1d090 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1d0a0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1d0b0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1d0c0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1d0d0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1d0e0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1d0f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d100 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1d110 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1d120 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1d130 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1d140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1d150 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1d160 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1d170 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1d180 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1d190 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1d1a0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1d1b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d1c0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1d1d0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1d1e0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1d1f0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1d200 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1d210 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1d220 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1d230 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1d240 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1d250 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1d260 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1d270 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1d280 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1d290 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1d2a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1d2b0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1d2c0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1d2d0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1d2e0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1d2f0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1d300 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1d310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1d320 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1d330 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1d340 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1d350 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1d360 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1d370 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1d380 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1d390 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1d3a0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1d3b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d3c0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1d3d0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1d3e0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1d3f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d400 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1d410 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1d420 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1d430 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1d440 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1d450 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1d460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d470 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1d480 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1d490 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1d4a0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1d4b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d4c0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1d4d0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1d4e0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1d4f0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1d500 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1d510 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1d520 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1d530 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1d540 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1d550 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1d560 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1d570 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1d580 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1d590 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1d5a0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1d5b0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1d5c0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1d5d0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1d5e0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1d5f0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1d600 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a   a hard upper.**
1d610 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20   bound set by a 
1d620 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
1d630 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d640 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
1d650 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
1d660 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1d670 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1d680 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
1d690 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
1d6a0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1d6b0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1d6c0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1d6d0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1d6e0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1d6f0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
1d700 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
1d710 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1d720 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1d730 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1d740 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1d750 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1d760 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1d770 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1d780 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1d790 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1d7a0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1d7b0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1d7c0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1d7d0 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
1d7e0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
1d7f0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
1d800 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
1d810 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
1d820 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
1d830 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
1d840 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
1d850 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
1d860 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
1d870 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
1d880 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
1d890 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
1d8a0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
1d8b0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
1d8c0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
1d8d0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
1d8e0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
1d8f0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
1d900 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
1d910 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
1d920 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
1d930 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
1d940 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
1d950 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1d960 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d970 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
1d980 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
1d990 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
1d9a0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1d9b0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1d9c0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
1d9d0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
1d9e0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
1d9f0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
1da00 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1da10 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
1da20 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
1da30 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
1da40 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
1da50 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
1da60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1da70 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73  .** {H12762} A s
1da80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1da90 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1daa0 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1dab0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1dac0 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73  positive changes
1dad0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
1dae0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1daf0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
1db00 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1db10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1db20 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
1db30 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
1db40 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20   upper.**       
1db50 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20     bound on the 
1db60 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69  size of C that i
1db70 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
1db80 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  -time..**.** {H1
1db90 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
1dba0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1dbb0 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1dbc0 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
1dbd0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
1dbe0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
1dbf0 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  te of the [datab
1dc00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1dc10 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
1dc20 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75  ** {H12769} A su
1dc30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1dc40 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1dc50 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
1dc60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1dc70 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1dc80 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1dc90 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1dca0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1dcb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dcc0 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
1dcd0 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
1dce0 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
1dcf0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1dd00 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1dd10 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1dd20 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1dd30 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1dd40 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48  ries {H12790} <H
1dd50 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  12760>.** KEYWOR
1dd60 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1dd70 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
1dd80 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1dd90 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1dda0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70  fine various asp
1ddb0 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62  ects of a [datab
1ddc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
1ddd0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1dde0 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62  imited in size b
1ddf0 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  y calls to [sqli
1de00 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1de10 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   The meanings of
1de20 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1de30 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  its are as follo
1de40 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ws:.**.** <dl>.*
1de50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1de60 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1de70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1de80 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1de90 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1dea0 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
1deb0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1dec0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1ded0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1dee0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1def0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1df00 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1df10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1df20 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1df30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1df40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1df50 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1df60 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1df70 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1df80 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
1df90 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1dfa0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1dfb0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1dfc0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1dfd0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1dfe0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1dff0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1e000 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1e010 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e020 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1e030 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1e040 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1e050 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e060 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1e070 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1e080 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e090 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1e0a0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1e0b0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1e0c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e0d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e0e0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1e0f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e100 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1e110 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1e120 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1e130 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1e140 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1e150 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1e160 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e170 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1e180 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e190 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e1a0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1e1b0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
1e1c0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e1d0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1e1e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e1f0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e200 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
1e210 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
1e220 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e230 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e240 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e250 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1e260 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1e270 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1e280 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
1e290 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
1e2a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1e2b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1e2c0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1e2d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e2e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1e2f0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1e300 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1e310 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1e320 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1e330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1e350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e360 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1e370 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1e380 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1e390 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1e3a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1e3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e3c0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1e3d0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1e3e0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1e3f0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1e400 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1e410 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1e420 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1e430 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e440 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1e450 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1e460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1e470 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1e480 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1e490 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1e4a0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1e4b0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1e4c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1e4d0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1e4e0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1e4f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e500 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1e510 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
1e520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e530 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
1e540 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
1e550 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
1e560 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1e570 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1e580 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1e590 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1e5a0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1e5b0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1e5c0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1e5d0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1e5e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1e5f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1e600 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1e610 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1e620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1e630 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1e640 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
1e650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1e660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e670 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e680 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1e690 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1e6a0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
1e6b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
1e6c0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
1e6d0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
1e6e0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1e6f0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
1e700 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
1e710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e720 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
1e730 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
1e740 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1e750 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
1e760 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e770 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
1e780 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
1e790 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1e7a0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1e7b0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1e7c0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1e7d0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1e7e0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
1e7f0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1e800 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1e810 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1e820 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1e830 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
1e840 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1e850 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1e860 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1e870 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1e880 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1e890 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1e8a0 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
1e8b0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1e8c0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1e8d0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1e8e0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1e8f0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1e900 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1e910 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1e920 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1e930 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1e940 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1e950 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1e960 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1e970 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1e980 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e990 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1e9a0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1e9b0 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1e9c0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1e9d0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a  bytes..**.** *pz
1e9e0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1e9f0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1ea00 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
1ea10 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66   end of the.** f
1ea20 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1ea30 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1ea40 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1ea50 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1ea60 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
1ea70 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1ea80 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1ea90 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
1eaa0 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
1eab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
1eac0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
1ead0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
1eae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1eaf0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
1eb00 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
1eb10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1eb20 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
1eb30 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1eb40 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1eb50 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
1eb60 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1eb70 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1eb80 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1eb90 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1eba0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1ebb0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1ebc0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31   to NULL..** {A1
1ebd0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
1ebe0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1ebf0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1ec00 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1ec10 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1ec20 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1ec30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1ec40 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1ec50 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1ec60 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1ec70 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
1ec80 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
1ec90 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1eca0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1ecb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ecc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ecd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ece0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1ecf0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1ed00 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1ed10 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1ed20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1ed30 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1ed40 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1ed50 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1ed60 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1ed70 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1ed80 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
1ed90 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1eda0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1edb0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1edc0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1edd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1ede0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1edf0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1ee00 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1ee10 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1ee20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1ee30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1ee40 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
1ee50 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
1ee60 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1ee70 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
1ee80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1ee90 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1eea0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1eeb0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1eec0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1eed0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1eee0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1eef0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1ef00 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1ef10 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1ef20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1ef30 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
1ef40 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1ef50 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1ef60 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1ef70 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1ef80 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1ef90 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1efa0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1efb0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1efc0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1efd0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1efe0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1eff0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1f000 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1f010 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1f020 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1f030 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1f040 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1f050 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1f060 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f070 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1f080 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1f090 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1f0a0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1f0b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1f0c0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1f0d0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
1f0e0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1f0f0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1f100 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1f110 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1f120 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1f130 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1f140 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1f150 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
1f160 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
1f170 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1f180 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
1f190 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
1f1a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1f1b0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
1f1c0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
1f1d0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1f1e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1f1f0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1f200 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
1f210 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1f220 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1f230 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1f240 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1f250 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1f260 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1f270 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1f280 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1f290 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1f2a0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
1f2b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1f2c0 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {H13011} The [sq
1f2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1f2e0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1f2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f300 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f310 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1f320 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1f330 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1f340 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1f350 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1f360 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
1f370 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {H13012} The [sq
1f380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1f390 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1f3a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1f3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f3c0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1f3d0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1f3e0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1f3f0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1f400 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1f410 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
1f420 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1f430 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48   order..**.** {H
1f440 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
1f450 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1f460 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f470 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1f480 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1f490 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1f4a0 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
1f4b0 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20  n zero, the SQL 
1f4c0 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  text is.**      
1f4d0 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53      read from zS
1f4e0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1f4f0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1f500 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1f510 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68  * {H13014} If th
1f520 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1f530 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f540 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1f550 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
1f560 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
1f570 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d  variants is non-
1f580 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
1f590 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79  t most nBytes by
1f5a0 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
1f5b0 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72     SQL text is r
1f5c0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a  ead from zSql..*
1f5d0 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e  *.** {H13015} In
1f5e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f5f0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50  e_v2(db,zSql,N,P
1f600 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74  ,pzTail)] and it
1f610 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20  s variants.**   
1f620 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53         if the zS
1f630 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  ql input text co
1f640 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e  ntains more than
1f650 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65   one SQL stateme
1f660 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  nt.**          a
1f670 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  nd pzTail is not
1f680 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54   NULL, then *pzT
1f690 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1f6a0 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20  oint to the.**  
1f6b0 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79          first by
1f6c0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1f6d0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1f6e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1f6f0 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ql..**          
1f700 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20  <todo>What does 
1f710 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f  *pzTail point to
1f720 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65   if there is one
1f730 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64   statement?</tod
1f740 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36  o>.**.** {H13016
1f750 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1f760 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1f770 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1f780 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29  ql,N,ppStmt,...)
1f790 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
1f7a0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1f7b0 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f  ants writes into
1f7c0 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74   *ppStmt a point
1f7d0 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1f7e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1f800 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  a pointer to NUL
1f810 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69  L if zSql contai
1f820 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ns.**          n
1f830 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
1f840 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20  n whitespace or 
1f850 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  comments..**.** 
1f860 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {H13019} The [sq
1f870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f880 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
1f890 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
1f8a0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1f8b0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
1f8c0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
1f8d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
1f8e0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1f8f0 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {H13021} Before
1f900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f910 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
1f920 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
1f930 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
1f940 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
1f950 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
1f960 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1f970 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c  an [SQLITE_OK]),
1f980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f990 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53  y first set *ppS
1f9a0 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  tmt to NULL..*/.
1f9b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1f9c0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
1f9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1f9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1f9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1fa00 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1fa10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1fa20 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1fa30 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1fa40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1fa50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1fa60 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1fa70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1fa80 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1fa90 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1faa0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1fab0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1fac0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1fad0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1fae0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1faf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1fb00 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
1fb10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1fb20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1fb30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1fb40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1fb50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1fb60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1fb70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1fb80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1fb90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1fba0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1fbb0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1fbc0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1fbd0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1fbe0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1fbf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1fc00 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1fc10 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1fc20 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1fc30 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1fc40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
1fc50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1fc60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1fc70 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1fc80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1fc90 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1fca0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1fcb0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1fcc0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1fcd0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1fce0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1fcf0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1fd00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1fd10 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1fd20 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1fd30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1fd40 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1fd50 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1fd60 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1fd70 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1fd80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1fd90 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
1fda0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1fdb0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1fdc0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1fdd0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1fde0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1fdf0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1fe00 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1fe10 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1fe20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1fe30 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1fe40 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1fe50 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1fe60 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1fe70 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1fe80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1fe90 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1fea0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1feb0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1fec0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
1fed0 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76 69  APIREF: Retrievi
1fee0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1fef0 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30   {H13100} <H1300
1ff00 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1ff10 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ff20 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
1ff30 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
1ff40 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
1ff50 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
1ff60 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
1ff70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
1ff80 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
1ff90 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
1ffa0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
1ffb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ffc0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1ffd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1ffe0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1fff0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  TS:.**.** {H1310
20000 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
20010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
20020 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
20030 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
20040 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
20050 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
20060 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
20070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20080 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
20090 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
200a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74  epare16_v2()], t
200b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
200c0 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ()] returns.**  
200d0 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
200e0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
200f0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f  inated string co
20100 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38  ntaining a UTF-8
20110 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20   rendering.**   
20120 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72         of the or
20130 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65  iginal SQL state
20140 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ment..**.** {H13
20150 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65  102} If the [pre
20160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20170 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
20180 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
20190 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
201a0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
201b0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
201c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
201d0 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
201e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
201f0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
20200 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
20210 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
20220 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
20230 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
20240 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
20250 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
20260 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
20270 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
20280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20290 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
202a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
202b0 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
202c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
202d0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
202e0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
202f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
20300 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
20310 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48   Value Object {H
20320 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15000} <S20200>.
20330 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
20340 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20350 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
20360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20370 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
20380 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
20390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
203a0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
203b0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
203c0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
203d0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
203e0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
203f0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
20400 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
20410 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20   stores. Values 
20420 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
20430 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
20440 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
20450 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
20460 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
20470 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
20480 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
20490 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
204a0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
204b0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
204c0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
204d0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
204e0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
204f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20500 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
20510 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
20520 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
20530 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
20540 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20550 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
20560 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
20570 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
20580 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
20590 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
205a0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
205b0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
205c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
205d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
205e0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
205f0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
20600 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
20610 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
20620 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
20630 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
20640 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
20650 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20660 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20670 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
20680 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
20690 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
206a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
206b0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
206c0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
206d0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
206e0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
206f0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
20700 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
20710 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
20720 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
20730 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
20740 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
20750 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
20760 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
20770 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
20780 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
20790 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
207a0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
207b0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
207c0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
207d0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
207e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
207f0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
20800 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
20810 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
20820 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
20830 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
20840 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
20850 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
20860 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
20870 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
20880 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
20890 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  een between prot
208a0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
208b0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
208c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
208d0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
208e0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
208f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20900 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20910 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
20920 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
20930 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
20940 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
20950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
20960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
20970 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
20980 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
20990 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
209a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
209b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
209c0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
209d0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
209e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
209f0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
20a00 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
20a10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
20a20 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
20a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20a40 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
20a50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
20a60 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
20a70 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
20a80 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
20a90 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
20aa0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20ab0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
20ac0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
20ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
20ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20af0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
20b00 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36  text Object {H16
20b10 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  001} <S20200>.**
20b20 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
20b30 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
20b40 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
20b50 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
20b60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
20b70 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
20b80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
20b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
20ba0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
20bb0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
20bc0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
20bd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
20be0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
20bf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
20c00 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20c10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
20c20 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
20c30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
20c40 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
20c50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
20c60 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
20c70 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
20c80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
20c90 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
20ca0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
20cb0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
20cc0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
20cd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
20ce0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
20cf0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
20d00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
20d10 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
20d20 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
20d30 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
20d40 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
20d50 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
20d60 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
20d70 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35  Statements {H135
20d80 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20  00} <S70300>.** 
20d90 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
20da0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
20db0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
20dc0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
20dd0 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
20de0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
20df0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
20e00 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
20e10 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ing}.**.** In th
20e20 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
20e30 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
20e40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
20e50 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
20e60 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
20e70 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
20e80 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
20e90 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  e of these forms
20ea0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20eb0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
20ec0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
20ed0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
20ee0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
20ef0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
20f00 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
20f10 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
20f20 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
20f30 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
20f40 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c  and VVV is an al
20f50 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
20f60 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20  meter name. The 
20f70 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
20f80 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
20f90 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
20fa0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
20fb0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
20fc0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
20fd0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
20fe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
20ff0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
21000 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
21010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21020 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
21030 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
21040 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
21050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21060 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
21070 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
21080 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
21090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
210a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
210b0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
210c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
210d0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
210e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
210f0 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74  set..** The left
21100 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
21110 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
21120 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
21130 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
21140 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
21150 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
21160 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
21170 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
21180 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
21190 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
211a0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
211b0 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64  ence..** The ind
211c0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
211d0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
211e0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
211f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
21200 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21210 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
21220 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
21230 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
21240 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
21250 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
21260 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
21270 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
21280 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
21290 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
212a0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
212b0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
212c0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
212d0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
212e0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
212f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
21300 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
21310 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
21320 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f  *.** In those ro
21330 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
21340 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
21350 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
21360 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21370 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
21380 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
21390 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
213a0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
213b0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
213c0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
213d0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
213e0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
213f0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
21400 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
21410 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
21420 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
21430 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
21440 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
21450 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
21460 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
21470 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
21480 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
21490 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
214a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
214b0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
214c0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
214d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
214e0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
214f0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
21500 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
21510 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
21520 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
21530 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
21540 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
21550 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
21560 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
21570 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
21580 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
21590 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
215a0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
215b0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
215c0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
215d0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
215e0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
215f0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
21600 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
21610 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
21620 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
21630 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
21640 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
21650 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
21660 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21670 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
21680 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21690 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
216a0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
216b0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
216c0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
216d0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
216e0 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  .  A zeroblob us
216f0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
21700 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
21710 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
21720 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
21730 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
21740 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
21750 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
21760 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
21770 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
21780 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
21790 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
217a0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
217b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
217c0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
217d0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
217e0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41  ] routines..** A
217f0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
21800 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
21810 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
21820 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
21830 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21840 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
21850 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
21860 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
21870 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21880 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
21890 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
218a0 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
218b0 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
218c0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
218d0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
218e0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
218f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21900 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
21910 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
21920 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
21930 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
21940 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21950 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
21960 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
21970 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
21980 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
21990 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
219a0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
219b0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
219c0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
219d0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
219e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
219f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
21a00 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
21a10 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
21a20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
21a30 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
21a40 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
21a50 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
21a60 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
21a70 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
21a80 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
21a90 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
21aa0 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
21ab0 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
21ac0 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
21ad0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
21ae0 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
21af0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
21b00 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
21b10 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
21b20 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
21b30 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
21b40 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
21b50 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
21b60 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21b70 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
21b80 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
21b90 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
21ba0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21bb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21bc0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
21bd0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
21be0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21bf0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
21c00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21c10 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
21c20 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21c30 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68  *.** {H13506} Th
21c40 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
21c50 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
21c60 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20  nizes tokens of 
21c70 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20  the forms.**    
21c80 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e        "?", "?NNN
21c90 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
21ca0 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73  ", and "@VVV" as
21cb0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c   SQL parameters,
21cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
21cd0 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
21ce0 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
21cf0 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20   more digits.** 
21d00 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
21d10 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
21d20 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
21d30 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72   more alphanumer
21d40 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ic.**          c
21d50 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a  haracters or "::
21d60 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  " optionally fol
21d70 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e  lowed by a strin
21d80 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  g containing.** 
21d90 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63           no spac
21da0 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64  es and contained
21db0 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65   within parenthe
21dc0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ses..**.** {H135
21dd0 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20  09} The initial 
21de0 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
21df0 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
21e00 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32  L..**.** {H13512
21e10 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
21e20 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65  n "?" SQL parame
21e30 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65  ter is one large
21e40 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20  r than the.**   
21e50 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69         largest i
21e60 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
21e70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66  meter to the lef
21e80 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20  t, or 1 if.**   
21e90 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69         the "?" i
21ea0 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  s the leftmost S
21eb0 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  QL parameter..**
21ec0 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65  .** {H13515} The
21ed0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e   index of an "?N
21ee0 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  NN" SQL paramete
21ef0 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72  r is the integer
21f00 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33   NNN..**.** {H13
21f10 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  518} The index o
21f20 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56  f an ":VVV", "$V
21f30 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53  VV", or "@VVV" S
21f40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  QL parameter is.
21f50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
21f60 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65  same as the inde
21f70 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63  x of leftmost oc
21f80 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65  currences of the
21f90 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
21fa0 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20    parameter, or 
21fb0 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  one more than th
21fc0 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
21fd0 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  over all.**     
21fe0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20       parameters 
21ff0 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74  to the left if t
22000 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74  his is the first
22010 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20   occurrence.**  
22020 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20          of this 
22030 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20  parameter, or 1 
22040 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c  if this is the l
22050 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65  eftmost paramete
22060 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31  r..**.** {H13521
22070 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
22080 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
22090 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51  ails with an [SQ
220a0 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20  LITE_RANGE].**  
220b0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66          error if
220c0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
220d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
220e0 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a  s less than 1.**
220f0 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65            or gre
22100 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f  ater than the co
22110 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54  mpile-time SQLIT
22120 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
22130 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  UMBER.**        
22140 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
22150 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c  ** {H13524} Call
22160 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22170 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22180 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
22190 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
221a0 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
221b0 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
221c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
221d0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
221e0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
221f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22200 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
22210 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c  ** {H13527} Call
22220 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22230 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22240 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
22250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
22260 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
22270 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
22280 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
22290 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30  N..**.** {H13530
222a0 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
222b0 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
222c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
222d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
222e0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
222f0 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
22300 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22310 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
22320 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61  * {H13533} In ca
22330 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22340 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
22350 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
22360 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
22370 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
22380 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
22390 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
223a0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
223b0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
223c0 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
223d0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
223e0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
223f0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
22400 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
22410 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
22420 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
22430 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  H13536} In calls
22440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22450 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
22460 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
22470 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22480 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
22490 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
224a0 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
224b0 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
224c0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
224d0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
224e0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
224f0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39  e..**.** {H13539
22500 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22520 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
22530 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22540 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
22550 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
22560 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22570 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
22580 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
22590 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
225a0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
225b0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
225c0 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
225d0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
225e0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
225f0 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
22600 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
22610 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
22620 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
22630 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
22640 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
22650 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
22660 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  H13542} In calls
22670 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22680 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
22690 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
226a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
226b0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
226c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
226d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
226e0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
226f0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
22700 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
22710 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
22720 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
22730 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
22740 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
22750 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
22760 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72  he value V befor
22770 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
22780 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20  .** {H13545} In 
22790 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
227a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
227b0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
227c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
227d0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
227e0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
227f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22800 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22810 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
22820 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
22830 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
22840 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
22850 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
22860 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
22870 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
22880 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73  e V after it has
22890 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
228a0 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  the value V..**.
228b0 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63  ** {H13548} In c
228c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
228d0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
228e0 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
228f0 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
22900 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f       is a BLOB o
22910 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
22920 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
22930 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
22940 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31  e..**.** {H13551
22950 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
22970 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
22980 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
22990 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
229a0 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
229b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
229c0 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
229d0 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
229e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
229f0 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
22a00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22a10 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
22a20 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
22a30 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
22a40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
22a50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
22a60 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
22a70 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
22a80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22a90 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
22aa0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
22ab0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22ac0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
22ad0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
22ae0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
22af0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
22b00 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
22b10 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
22b20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
22b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22b40 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
22b50 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
22b60 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
22b70 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
22b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22b90 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
22ba0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
22bb0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
22bc0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
22bd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22be0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
22bf0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
22c00 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
22c10 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
22c20 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
22c30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22c40 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
22c50 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d  ameters {H13600}
22c60 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
22c70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
22c80 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
22c90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
22ca0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
22cb0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
22cc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
22cd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
22ce0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
22cf0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
22d00 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
22d10 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
22d20 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
22d30 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
22d40 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
22d50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22d60 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
22d70 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
22d80 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
22d90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
22da0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
22db0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
22dc0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
22dd0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
22de0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
22df0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
22e00 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
22e10 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
22e20 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
22e30 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
22e40 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
22e50 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
22e60 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
22e70 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
22e80 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
22e90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22ea0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
22eb0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
22ec0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22ed0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
22ee0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22ef0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22f00 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22f10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22f20 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {H13601} The [s
22f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22f40 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
22f50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22f60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
22f70 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
22f80 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
22f90 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
22fa0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
22fc0 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
22fd0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
22fe0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
22ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23000 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
23010 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
23020 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
23030 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
23040 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53  eter {H13620} <S
23050 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70300>.**.** Thi
23060 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
23070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23080 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
23090 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61  -th.** [SQL para
230a0 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65  meter] in a [pre
230b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
230c0 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
230d0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
230e0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
230f0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
23100 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
23110 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
23120 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
23130 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
23140 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
23150 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
23160 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
23170 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
23180 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
23190 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
231a0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
231b0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
231c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
231d0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
231e0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
231f0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
23200 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
23210 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
23220 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
23230 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  eters"..**.** Th
23240 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
23250 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
23260 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
23270 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
23280 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
23290 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
232a0 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
232b0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
232c0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
232d0 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
232e0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
232f0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
23300 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
23310 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
23320 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
23330 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
23340 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
23350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23360 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
23370 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23380 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
23390 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
233a0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
233b0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
233c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
233d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
233e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
233f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23400 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
23410 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23420 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13621} The [sql
23430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23440 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ter_name(S,N)] i
23450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55  .**          a U
23470 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
23480 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  f the name of th
23490 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
234a0 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  in.**          t
234b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
234c0 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
234d0 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
234e0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
234f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
23500 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
23510 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
23520 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
23530 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
23540 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
23550 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
23560 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
23570 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
23580 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
23590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
235a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
235b0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
235c0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
235d0 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
235e0 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
235f0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
23600 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
23610 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
23620 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
23630 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
23640 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
23650 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
23660 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
23670 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
23680 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
23690 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
236a0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
236b0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
236c0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
236d0 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
236e0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
236f0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
23700 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
23710 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23720 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
23730 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
23740 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
23750 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
23770 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
23780 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
23790 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
237a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
237b0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
237c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
237d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
237e0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
237f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23800 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13641} The [sqli
23810 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23820 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69  er_index(S,N)] i
23830 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
23850 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
23860 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b  rameter in the [
23870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23880 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
23890 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74  S whose name mat
238a0 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73  ches the UTF-8 s
238b0 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66  tring N, or 0 if
238c0 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20   there is.**    
238d0 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a        no match..
238e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
238f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23900 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
23910 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
23920 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
23930 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
23940 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
23950 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23960 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
23970 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
23980 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
23990 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
239a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
239b0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
239c0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
239d0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
239e0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
239f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23a00 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
23a10 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
23a20 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
23a30 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
23a40 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23a50 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b  * {H13661} The [
23a60 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23a70 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
23a80 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
23a90 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
23aa0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
23ab0 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
23ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23ad0 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
23ae0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
23af0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
23b00 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
23b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
23b20 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
23b30 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
23b40 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
23b50 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
23b60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
23b70 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
23b80 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
23b90 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
23ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23bb0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
23bc0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
23bd0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
23be0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
23bf0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
23c00 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
23c10 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
23c20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23c30 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65  .** {H13711} The
23c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23c50 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
23c60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23c70 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
23c80 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
23c90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
23ca0 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
23cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23cc0 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
23cd0 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20        or 0 if S 
23ce0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
23cf0 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  e a result set..
23d00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
23d10 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
23d20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23d30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23d40 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
23d50 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
23d60 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
23d70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
23d80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
23d90 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
23da0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
23db0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
23dc0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
23dd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23de0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
23df0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
23e00 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
23e10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
23e20 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
23e30 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
23e40 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
23e50 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
23e60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
23e70 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
23e80 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
23e90 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
23ea0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23eb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23ec0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
23ed0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
23ee0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23ef0 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
23f00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23f10 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
23f20 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
23f30 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
23f40 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
23f50 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
23f60 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
23f70 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
23f80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23f90 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
23fa0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
23fb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
23fc0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
23fd0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
23fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
23ff0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24000 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
24010 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
24020 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
24030 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
24040 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
24050 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
24060 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
24070 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
24080 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
24090 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
240a0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
240b0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
240c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
240d0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
240e0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
240f0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
24100 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
24110 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
24120 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
24130 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
24140 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
24150 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
24160 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
24170 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
24180 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
24190 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
241a0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
241b0 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
241c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
241d0 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {H13721} A succe
241e0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
241f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
24200 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
24210 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
24220 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24230 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24240 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
24250 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
24260 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
24270 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
24280 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
24290 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
242a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
242b0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
242c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
242d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
242e0 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  H13723} A succes
242f0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
24300 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24310 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
24320 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
24330 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24340 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24350 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
24360 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
24370 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
24380 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
24390 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
243a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
243b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
243c0 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
243d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
243e0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  16 string.**    
243f0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
24400 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24410 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54  **.** {H13724} T
24420 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24430 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
24440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24450 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
24460 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
24470 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
24480 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
24490 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
244a0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
244b0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
244c0 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
244d0 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
244e0 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74  ** {H13725} If t
244f0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
24500 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24510 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
24520 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24540 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
24550 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
24560 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
24570 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
24580 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
24590 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20  .**.** {H13726} 
245a0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
245b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
245c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
245d0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
245e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
245f0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
24600 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
24610 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
24620 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
24630 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
24640 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
24650 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
24660 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
24670 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
24680 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
24690 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37  d..**.** {H13727
246a0 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
246b0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
246c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
246d0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
246e0 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
246f0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
24700 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
24710 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
24720 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
24730 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
24740 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
24750 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
24760 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
24770 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
24780 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
247a0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
247b0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
247c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
247d0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
247e0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
247f0 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3740} <S10700>.*
24800 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24810 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
24820 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
24830 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
24840 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
24850 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
24860 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
24870 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
24880 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
24890 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
248a0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
248b0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
248c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
248d0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
248e0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
248f0 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
24900 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
24910 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
24920 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
24930 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
24940 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
24950 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
24960 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
24970 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
24980 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
24990 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
249a0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
249b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
249c0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
249d0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
249e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
249f0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24a00 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
24a10 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
24a20 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
24a30 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
24a40 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
24a50 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
24a60 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
24a70 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
24a80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
24a90 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
24aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24ab0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
24ac0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
24ad0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
24ae0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24af0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
24b00 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
24b10 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
24b20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
24b30 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
24b40 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
24b50 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
24b60 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
24b70 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
24b80 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
24b90 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
24ba0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
24bb0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
24bc0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
24bd0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
24be0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
24bf0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
24c00 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
24c10 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
24c20 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
24c30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
24c40 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
24c50 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
24c60 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
24c70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
24c80 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
24c90 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
24ca0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
24cb0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
24cc0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
24cd0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
24ce0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
24cf0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
24d00 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
24d10 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
24d20 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
24d30 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
24d40 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
24d50 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
24d60 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
24d70 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
24d80 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
24d90 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
24da0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
24db0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
24dc0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
24dd0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
24de0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
24df0 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
24e00 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
24e10 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
24e20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24e30 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
24e40 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
24e50 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
24e60 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
24e70 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
24e80 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
24e90 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
24ea0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24eb0 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
24ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24ed0 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
24ee0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24ef0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24f00 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
24f10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24f20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24f30 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
24f40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24f50 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24f60 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
24f70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24f80 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
24f90 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
24fa0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24fb0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24fc0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24fe0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24ff0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25000 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25010 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
25020 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25030 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25040 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
25050 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
25060 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
25070 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
25080 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
25090 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
250a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
250b0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
250c0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
250d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
250e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
250f0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
25100 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
25110 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
25120 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25130 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25140 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25150 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25160 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25170 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25180 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25190 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
251a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
251b0 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
251c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
251d0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
251e0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
251f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
25200 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
25210 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
25220 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
25230 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
25240 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25250 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
25260 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
25270 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
25280 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25290 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
252a0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
252b0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
252c0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
252d0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
252e0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
252f0 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
25300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25310 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
25320 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25330 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25340 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
25350 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25360 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
25370 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
25380 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
25390 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
253a0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
253b0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
253c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
253d0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
253e0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
253f0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
25400 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25410 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25430 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25440 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25450 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25460 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
25470 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25480 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
25490 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
254a0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
254b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
254c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
254d0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
254e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
254f0 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
25500 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
25510 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
25520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25530 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
25540 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
25550 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
25560 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
25570 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
25580 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
25590 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
255a0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
255b0 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
255c0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
255d0 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
255e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
255f0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
25600 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25610 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
25620 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
25630 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
25640 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25650 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
25660 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
25670 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
25680 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
25690 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
256a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
256b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
256c0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
256d0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
256e0 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
256f0 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
25700 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
25710 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
25720 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25730 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
25740 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
25750 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
25760 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
25770 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
25780 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
25790 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
257a0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
257b0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
257c0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
257d0 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
257e0 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
257f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25800 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
25810 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
25820 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
25830 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
25840 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
25850 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
25860 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
25870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
25880 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
25890 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
258a0 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
258b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
258c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
258d0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
258e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
258f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
25900 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
25910 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
25920 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
25930 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
25940 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
25950 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
25960 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
25970 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
25980 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
25990 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
259a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
259b0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
259c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
259d0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
259e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
259f0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25a00 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25a10 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
25a20 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25a30 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
25a40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25a50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25a60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
25a70 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
25a80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25a90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25aa0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
25ab0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25ac0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25ad0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25ae0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
25af0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25b00 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
25b10 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
25b20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
25b30 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
25b40 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
25b50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
25b60 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
25b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25b80 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
25b90 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
25ba0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
25bb0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
25bc0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
25bd0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
25be0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
25bf0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
25c00 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
25c10 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
25c20 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
25c30 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
25c40 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
25c50 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
25c60 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
25c70 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
25c80 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
25c90 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
25ca0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
25cb0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
25cc0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
25cd0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
25ce0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
25cf0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
25d00 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
25d10 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
25d20 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
25d30 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
25d40 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
25d50 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
25d60 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
25d70 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
25d80 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
25d90 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
25da0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
25db0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
25dc0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
25dd0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
25de0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
25df0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
25e00 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
25e10 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
25e20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
25e30 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
25e40 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
25e50 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
25e60 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
25e70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
25e80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
25e90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
25ea0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
25eb0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
25ec0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
25ed0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
25ee0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
25ef0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
25f00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
25f10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
25f20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
25f30 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
25f40 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
25f50 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
25f60 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
25f70 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
25f80 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
25f90 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
25fa0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
25fb0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20  **.** {H13761}  
25fc0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25fd0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
25fe0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
25ff0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  N)] returns a.**
26000 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d             zero-
26010 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
26020 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
26030 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
26040 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20  datatype.**     
26050 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62        of the tab
26060 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
26070 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74  ppears as the Nt
26080 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
26090 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
260a0 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
260b0 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
260c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
260d0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
260e0 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  H13762}  A succe
260f0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
26100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
26110 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
26120 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
26130 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
26140 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
26150 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
26160 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
26170 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
26180 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
26190 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
261a0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
261b0 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
261c0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
261d0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
261e0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
261f0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
26200 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
26210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26220 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
26230 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
26240 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
26250 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
26260 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
26270 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
26280 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
26290 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
262a0 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
262b0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68          or if th
262c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
262d0 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  S is an expressi
262e0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72  on or subquery r
262f0 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ather.**        
26300 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20     than a table 
26310 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20  column, or if a 
26320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
26330 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20  n failure.**    
26340 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
26350 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f  ring encoding co
26360 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a  nversions, then.
26370 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c  **           cal
26380 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
26390 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
263a0 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
263b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
263c0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
263d0 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
263e0 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
263f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26400 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
26410 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26420 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26430 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
26440 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
26450 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
26460 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
26470 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
26480 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
26490 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
264a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
264b0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
264c0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
264d0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
264e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
264f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26500 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
26510 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
26520 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
26530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26540 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26550 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
26560 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
26570 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
26580 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
26590 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
265a0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
265b0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
265c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
265d0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
265e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
265f0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
26600 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
26610 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
26620 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
26630 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
26640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26650 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
26660 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26670 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
26680 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26690 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
266a0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
266b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
266c0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
266d0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
266e0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
266f0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
26700 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
26710 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26720 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
26730 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
26740 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
26750 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26760 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
26770 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
26780 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
26790 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
267a0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
267b0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
267c0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
267d0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
267e0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
267f0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
26800 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
26810 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
26820 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
26830 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
26840 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
26850 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
26860 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
26870 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
26880 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
26890 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
268a0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
268b0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
268c0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
268d0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
268e0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
268f0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
26900 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
26910 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
26920 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
26930 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
26940 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26950 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
26960 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
26970 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
26980 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
26990 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
269a0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
269b0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
269c0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
269d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
269e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
269f0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
26a00 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
26a10 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
26a20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26a30 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
26a40 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
26a50 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
26a60 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
26a70 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
26a80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
26a90 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
26aa0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
26ab0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
26ac0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
26ad0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
26ae0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
26af0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
26b00 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
26b10 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
26b20 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
26b30 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
26b40 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
26b50 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
26b60 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
26b70 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
26b80 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
26b90 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
26ba0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
26bb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
26bc0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
26bd0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
26be0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
26bf0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
26c00 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
26c10 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26c20 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
26c30 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
26c40 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
26c50 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
26c60 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
26c70 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
26c80 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
26c90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
26ca0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
26cb0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
26cc0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
26cd0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26ce0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
26cf0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
26d00 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
26d10 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
26d20 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
26d30 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
26d40 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
26d50 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
26d60 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
26d70 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
26d80 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
26d90 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26da0 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
26db0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
26dc0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
26dd0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
26de0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
26df0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
26e00 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
26e10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
26e20 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
26e30 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
26e40 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
26e50 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
26e60 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
26e70 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
26e80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
26e90 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
26ea0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
26eb0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
26ec0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
26ed0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
26ee0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
26ef0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
26f00 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
26f10 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
26f20 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
26f30 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
26f40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
26f50 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
26f60 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
26f70 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
26f80 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
26f90 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
26fa0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
26fb0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
26fc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
26fd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
26fe0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
26ff0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
27000 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
27010 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
27020 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
27030 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
27040 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
27050 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
27060 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
27070 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27080 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
27090 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
270a0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
270b0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
270c0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
270d0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
270e0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
270f0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
27100 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
27110 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
27120 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
27130 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
27140 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27150 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
27160 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
27170 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
27180 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
271a0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
271b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
271c0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
271d0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
271e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
271f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
27200 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
27210 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
27220 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
27230 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
27240 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
27250 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
27260 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
27270 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
27280 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
27290 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
272a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
272b0 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20  H13202}  If the 
272c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
272d0 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
272e0 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a  to be run, then.
272f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
27300 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
27310 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
27320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27330 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
27340 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72     completion or
27350 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61   until it is rea
27360 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f  dy to return ano
27370 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a  ther row of the.
27380 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73  **           res
27390 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69  ult set, or unti
273a0 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l an [sqlite3_in
273b0 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
273c0 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  upt].**         
273d0 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20    or a run-time 
273e0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
273f0 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68  .** {H15304}  Wh
27400 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
27410 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
27420 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
27430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27440 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f  *           S to
27450 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
27460 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  on, the function
27470 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
27480 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DONE]..**.** {H
27490 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
274a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
274b0 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
274c0 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
274d0 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  dy to.**        
274e0 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65     return anothe
274f0 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
27500 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
27510 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
27520 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d  ..**.** {H15308}
27530 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b    If a call to [
27540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27550 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a   encounters an.*
27560 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27570 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
27580 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
27590 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
275a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
275b0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
275c0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
275d0 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
275e0 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
275f0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
27600 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
27610 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
27620 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20  **.** {H15310}  
27630 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
27640 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
27650 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
27660 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
27670 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
27680 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
27690 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
276a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
276b0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
276c0 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
276d0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
276e0 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
276f0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
27700 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
27710 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27720 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27730 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  ], then the func
27740 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
27750 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27760 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
27770 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
27780 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
27790 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
277a0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
277b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
277c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
277d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
277e0 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
277f0 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
27800 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
27810 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
27820 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
27830 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
27840 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
27850 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
27860 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20  13771}  After a 
27870 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27880 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72  _step(S)] that r
27890 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
278a0 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  OW],.**         
278b0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    the [sqlite3_d
278c0 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f  ata_count(S)] ro
278d0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
278e0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
278f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
27900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
27910 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
27920 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
27930 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  H13772}  After [
27940 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27950 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
27960 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
27970 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
27980 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
27990 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
279a0 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
279b0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a  n called on the.
279c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
279d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
279e0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
279f0 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
27a00 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
27a10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
27a20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
27a30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
27a40 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20  reset],.**      
27a50 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
27a60 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
27a70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27a80 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
27a90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27aa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27ab0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27ac0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
27ad0 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48  tal Datatypes {H
27ae0 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c  10265} <S10110><
27af0 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10120>.** KEYWO
27b00 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
27b10 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20  .**.** {H10266} 
27b20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
27b30 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
27b40 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
27b50 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
27b60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
27b70 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
27b80 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
27b90 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
27ba0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
27bb0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
27bc0 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
27bd0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
27be0 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
27bf0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
27c00 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
27c10 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
27c20 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
27c30 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
27c40 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
27c50 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
27c60 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
27c70 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
27c80 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
27c90 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
27ca0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
27cb0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
27cc0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
27cd0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
27ce0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
27cf0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
27d00 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
27d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
27d20 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
27d30 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
27d40 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
27d50 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
27d60 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
27d70 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
27d80 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
27d90 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
27da0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
27db0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
27dc0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
27dd0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
27de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27df0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
27e00 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33  rom A Query {H13
27e10 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  800} <S10700>.**
27e20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
27e30 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
27e40 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
27e50 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
27e60 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71  he "result set q
27e70 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e  uery" interface.
27e80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27e90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
27ea0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
27eb0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
27ec0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
27ed0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
27ee0 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72   query.  In ever
27ef0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
27f00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
27f10 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
27f20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27f30 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
27f40 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
27f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
27f60 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
27f70 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
27f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27f90 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
27fa0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
27fb0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
27fc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
27fd0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
27fe0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
27ff0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
28000 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
28010 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
28020 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
28030 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
28040 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  dex 0..**.** If 
28050 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28060 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
28070 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
28080 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
28090 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
280a0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
280b0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
280c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
280d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
280e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
280f0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
28100 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
28110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28120 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
28130 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
28140 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
28150 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28160 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
28170 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
28180 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
28190 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
281a0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
281b0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
281c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
281d0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
281e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
281f0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
28200 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
28210 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
28220 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
28230 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
28240 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28250 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
28260 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28270 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
28280 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
28290 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
282a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
282b0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
282c0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
282d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
282e0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
282f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
28300 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
28310 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28320 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28330 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28340 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
28350 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
28360 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
28370 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
28380 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
28390 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
283a0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
283b0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
283c0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
283d0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
283e0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
283f0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
28400 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
28410 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
28420 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
28430 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
28440 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
28450 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
28460 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
28470 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
28480 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
28490 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
284a0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
284b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
284c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
284d0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
284e0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
284f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
28500 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
28510 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
28520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28530 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
28540 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
28550 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
28560 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
28570 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
28580 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28590 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
285a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
285b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
285c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
285d0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
285e0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
285f0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
28600 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
28610 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28620 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
28630 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
28640 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
28650 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
28660 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
28670 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
28680 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
28690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
286a0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
286b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
286c0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
286d0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
286e0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
286f0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
28700 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28710 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28720 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
28730 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
28740 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
28750 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
28760 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
28770 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
28780 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
28790 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
287a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
287b0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
287c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
287d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
287e0 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
287f0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
28810 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28820 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
28830 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
28840 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
28850 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
28860 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
28870 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
28880 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
28890 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
288a0 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
288b0 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
288c0 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
288d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
288e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
288f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28900 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
28910 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
28920 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
28930 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
28940 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
28950 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
28960 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
28970 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65  of UTF-8..** The
28980 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28990 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
289a0 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
289b0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
289c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
289d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
289e0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
289f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28a00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28a10 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
28a20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28a30 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
28a40 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
28a50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
28a60 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
28a70 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
28a80 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
28a90 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28aa0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28ab0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
28ac0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
28ad0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
28ae0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
28af0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
28b00 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
28b10 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
28b20 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
28b30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28b40 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
28b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28b60 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
28b70 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
28b80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
28b90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
28ba0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
28bb0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
28bc0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
28bd0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
28be0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
28bf0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
28c00 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
28c10 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
28c20 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
28c30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
28c40 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
28c50 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
28c60 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
28c70 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
28c80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
28c90 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
28ca0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
28cb0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
28cc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28cd0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
28ce0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
28cf0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
28d00 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
28d10 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
28d20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
28d30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28d40 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
28d50 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28d60 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
28d70 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
28d80 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
28d90 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
28da0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28db0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28dc0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28dd0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28de0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28df0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28e00 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28e10 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28e20 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
28e30 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
28e40 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
28e50 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
28e60 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
28e70 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
28e80 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
28e90 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
28ea0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
28eb0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
28ec0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28ed0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
28ee0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
28ef0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
28f00 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28f10 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
28f20 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
28f30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
28f40 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
28f50 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
28f60 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
28f70 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
28f80 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
28f90 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
28fa0 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
28fb0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
28fc0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
28fd0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
28fe0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
28ff0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29000 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29010 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
29020 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29030 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29040 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
29050 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
29060 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29070 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
29080 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
29090 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
290a0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
290b0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
290c0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
290d0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
290e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
290f0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
29100 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
29110 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
29120 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
29130 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
29140 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
29150 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
29160 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
29170 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
29180 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
29190 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
291a0 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
291b0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
291c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
291d0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
291e0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
291f0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
29200 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
29210 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
29220 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
29230 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
29240 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
29250 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
29260 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
29270 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
29280 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
29290 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
292a0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
292b0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
292c0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
292d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
292e0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
292f0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
29300 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29310 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
29320 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
29330 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
29340 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
29350 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
29360 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
29370 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
29380 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
29390 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
293a0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
293b0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
293c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
293d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
293e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
293f0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
29400 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
29410 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
29420 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
29430 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
29440 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
29450 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
29460 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
29470 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29480 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
29490 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
294a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
294b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
294c0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
294d0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
294e0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
294f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29500 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29510 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
29520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29530 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
29540 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29550 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
29560 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
29570 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29580 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
29590 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
295a0 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
295b0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
295c0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
295d0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
295e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
295f0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
29600 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
29610 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
29620 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
29630 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
29640 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
29650 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
29660 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
29670 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
29680 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
29690 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
296a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
296b0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
296c0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
296d0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
296e0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
296f0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
29700 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
29710 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
29720 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
29730 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
29740 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
29750 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
29760 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
29770 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
29780 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
29790 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
297a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
297b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
297c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
297d0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
297e0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
297f0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
29800 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29810 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
29820 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
29830 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29840 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
29850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29860 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
29870 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
29880 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
29890 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
298a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
298b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
298c0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
298d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
298e0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
298f0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
29900 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
29910 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
29920 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
29930 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
29940 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
29950 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
29960 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
29970 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
29980 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
29990 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
299a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
299b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
299c0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
299d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
299e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
299f0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
29a00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
29a10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
29a20 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
29a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29a40 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
29a50 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
29a60 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
29a70 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
29a80 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
29a90 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
29aa0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
29ab0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29ac0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
29ad0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29ae0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29af0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
29b00 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
29b10 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
29b20 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
29b30 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
29b40 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
29b50 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
29b60 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
29b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29b80 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
29b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29ba0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
29bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
29bc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
29bd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
29be0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
29bf0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
29c00 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
29c10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
29c20 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
29c30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
29c40 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
29c50 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
29c60 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
29c70 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29c80 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
29c90 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
29ca0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
29cb0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
29cc0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
29cd0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
29ce0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
29cf0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
29d00 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b  * {H13803} The [
29d10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29d20 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
29d30 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
29d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
29d50 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
29d60 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
29d70 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
29d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
29d90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29da0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42  ment] S into a B
29db0 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74  LOB and then ret
29dc0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
29dd0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
29de0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
29df0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36  e..**.** {H13806
29e00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29e10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
29e20 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29e30 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
29e40 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
29e50 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20  tes in the BLOB 
29e60 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
29e70 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
29e80 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
29e90 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
29ea0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
29eb0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
29ed0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
29ee0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29ef0 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
29f00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
29f10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
29f20 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
29f30 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
29f40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29f50 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29f60 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
29f70 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
29f80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
29f90 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
29fa0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
29fb0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
29fc0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
29fd0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
29fe0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
29ff0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2a000 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a020 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
2a030 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {H13812} The [s
2a040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a050 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
2a060 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2a070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2a080 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2a090 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a0a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2a0b0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2a0c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a0d0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2a0e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2a0f0 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
2a100 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2a110 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
2a120 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35  e..**.** {H13815
2a130 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a140 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
2a150 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a160 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a170 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a180 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a190 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a1a0 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a1b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a1c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a1d0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2a1e0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2a1f0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2a200 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
2a210 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
2a220 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
2a230 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
2a240 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
2a250 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2a260 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2a270 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2a280 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2a290 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a2a0 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
2a2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2a2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a2d0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
2a2e0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2a2f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2a300 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2a310 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2a320 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54  **.** {H13821} T
2a330 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2a340 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
2a350 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2a360 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a370 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2a380 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2a390 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a3a0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2a3b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a3c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2a3d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a3e0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
2a3f0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2a400 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2a410 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2a420 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d  ..**.** {H13824}
2a430 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a440 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
2a450 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2a460 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2a470 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2a480 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a490 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a4a0 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2a4b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a4c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a4d0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2a4e0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2a4f0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2a500 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2a510 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
2a520 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2a530 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
2a540 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2a550 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2a560 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2a570 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
2a580 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a590 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2a5a0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2a5b0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2a5c0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2a5d0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2a5e0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2a5f0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2a600 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2a610 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2a620 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
2a630 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a640 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a650 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2a660 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2a670 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a680 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30  S..**.** {H13830
2a690 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a6a0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29  olumn_value(S,N)
2a6b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a6c0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2a6d0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20    pointer to an 
2a6e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a6f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a700 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ct for the.**   
2a710 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2a720 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a730 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a740 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2a750 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2a760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a770 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  S..*/.const void
2a780 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a790 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2a7a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a7b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a7c0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2a7d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a7e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a7f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2a800 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a810 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2a820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a830 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2a840 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2a850 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a860 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2a870 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a880 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a8a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a8b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2a8c0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a8d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a8e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a8f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a900 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a920 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a930 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2a940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a950 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2a960 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2a970 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2a980 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2a990 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a9a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2a9b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2a9c0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2a9d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2a9e0 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30   {H13300} <S7030
2a9f0 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
2aa00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
2aa10 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2aa20 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2aa30 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2aa40 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2aa50 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2aa60 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
2aa70 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
2aa80 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
2aa90 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
2aaa0 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
2aab0 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
2aac0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2aad0 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
2aae0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
2aaf0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2ab00 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2ab10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
2ab20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2ab30 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2ab40 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
2ab50 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
2ab60 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ab70 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
2ab80 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2ab90 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
2aba0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
2abb0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
2abc0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
2abd0 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
2abe0 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
2abf0 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
2ac00 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
2ac10 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f  errupt]..** Inco
2ac20 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
2ac30 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
2ac40 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
2ac50 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
2ac60 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2ac70 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
2ac80 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
2ac90 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
2aca0 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
2acb0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
2acc0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2acd0 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {H11302} The [s
2ace0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2acf0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
2ad00 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
2ad10 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2ad20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
2ad30 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
2ad40 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2ad50 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
2ad60 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
2ad70 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
2ad80 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {H11304} If the 
2ad90 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ada0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2adb0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2adc0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2add0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ade0 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
2adf0 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
2ae00 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
2ae10 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
2ae20 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
2ae30 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
2ae40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2ae50 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2ae60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ae70 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2ae80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2ae90 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
2aea0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
2aeb0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2aec0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2aed0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2aee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aef0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2af00 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2af10 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2af20 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2af30 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
2af40 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2af50 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2af60 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2af70 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2af80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2af90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2afa0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2afb0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2afc0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2afd0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2afe0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2aff0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
2b000 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
2b010 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2b020 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2b030 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b040 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
2b050 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
2b060 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2b070 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
2b080 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
2b090 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b0a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b0b0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b0c0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2b0d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b0e0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b0f0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2b100 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
2b110 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
2b120 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2b130 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2b140 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2b150 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2b160 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b170 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2b180 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
2b190 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
2b1a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2b1b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2b1c0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2b1d0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2b1e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2b1f0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2b200 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
2b210 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2b220 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2b230 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2b240 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2b250 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
2b260 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b270 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2b280 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2b290 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
2b2a0 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
2b2b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2b2c0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2b2d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b2e0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
2b2f0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2b300 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b320 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2b330 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2b340 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
2b350 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
2b360 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2b370 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2b380 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b390 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b3a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2b3b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b3c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b3d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2b3e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
2b3f0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2b400 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2b410 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2b420 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2b430 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2b440 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b450 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2b460 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2b470 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2b480 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2b490 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2b4a0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2b4b0 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
2b4c0 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
2b4d0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
2b4e0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
2b4f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
2b500 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
2b510 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
2b520 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
2b530 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
2b540 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b550 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
2b560 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b570 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
2b580 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b590 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b5a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b5b0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2b5c0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2b5d0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2b5e0 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
2b5f0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
2b600 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
2b610 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2b620 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
2b630 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
2b640 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
2b650 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
2b660 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
2b670 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
2b680 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
2b690 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2b6a0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2b6b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2b6c0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2b6d0 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
2b6e0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2b6f0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2b700 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
2b710 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
2b720 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
2b730 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2b740 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2b750 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
2b760 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
2b770 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2b780 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2b790 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2b7a0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2b7b0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
2b7c0 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
2b7d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
2b7e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
2b7f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2b800 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2b810 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2b820 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2b830 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
2b840 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
2b850 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
2b860 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2b870 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2b880 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2b890 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2b8a0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
2b8b0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2b8c0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2b8d0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2b8e0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2b8f0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2b900 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2b910 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2b920 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
2b930 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2b940 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
2b950 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2b960 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
2b970 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2b980 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2b990 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2b9a0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2b9b0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2b9c0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2b9d0 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
2b9e0 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
2b9f0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2ba00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2ba10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2ba20 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2ba30 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2ba40 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2ba50 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2ba60 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2ba70 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2ba80 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
2ba90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2baa0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2bab0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2bac0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2bad0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2bae0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2baf0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2bb00 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2bb10 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2bb20 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2bb30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2bb40 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2bb50 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2bb60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2bb70 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2bb80 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2bb90 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2bba0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
2bbb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2bbc0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2bbd0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2bbe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2bbf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2bc00 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2bc10 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2bc20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2bc30 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
2bc40 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
2bc50 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
2bc60 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2bc70 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2bc80 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2bc90 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2bca0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2bcb0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2bcc0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2bcd0 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
2bce0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2bcf0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2bd00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2bd10 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2bd20 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
2bd30 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
2bd40 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2bd50 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2bd60 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2bd70 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
2bd80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2bd90 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2bda0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2bdb0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2bdc0 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
2bdd0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2bde0 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
2bdf0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2be00 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2be10 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2be20 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2be30 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2be40 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2be50 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2be60 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2be70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2be80 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2be90 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2bea0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2beb0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2bec0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2bed0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2bee0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2bef0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2bf00 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2bf10 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2bf20 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2bf30 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2bf40 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2bf50 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2bf60 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
2bf70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2bf80 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68  *.** {H16103} Th
2bf90 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2bfa0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2bfb0 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65  interface behave
2bfc0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
2bfd0 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69        like [sqli
2bfe0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bff0 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20  ion()] in every 
2c000 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20  way except that 
2c010 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
2c020 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46  nterprets the zF
2c030 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75  unctionName argu
2c040 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2c050 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2c060 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2c070 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2c080 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2c090 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2c0a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2c0b0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2c0c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  vocation of.**  
2c0d0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2c0e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c0f0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2c100 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
2c110 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  isters.**       
2c120 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2c130 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c140 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2c150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2c160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2c170 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2c180 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c190 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2c1a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2c1b0 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2c1c0 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2c1d0 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2c1e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2c1f0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2c200 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2c210 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c220 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2c230 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c  **          repl
2c240 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53  aces the P, F, S
2c250 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2c260 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2c270 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2c280 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2c290 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2c2a0 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2c2b0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2c2c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c2d0 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2c2e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a  face fails with.
2c2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
2c300 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
2c310 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74  LITE_ERROR] if t
2c320 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c330 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2c340 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2c350 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2c360 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2c370 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2c380 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74  .** {H16118} Eit
2c390 68 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55  her F must be NU
2c3a0 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61  LL and S and L a
2c3b0 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65  re non-NULL or e
2c3c0 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20  lse F.**        
2c3d0 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e    is non-NULL an
2c3e0 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55  d S and L are NU
2c3f0 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  LL, otherwise.**
2c400 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c410 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c420 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2c430 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  ,L)] returns [SQ
2c440 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a  LITE_ERROR]..**.
2c450 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20  ** {H16121} The 
2c460 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c470 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d  function(D,...)]
2c480 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2c490 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2c4a0 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2c4b0 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  of [SQLITE_BUSY]
2c4c0 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20   if there exist 
2c4d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c4e0 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ents].**        
2c4f0 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74    associated wit
2c500 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2c510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2c520 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68  *.** {H16124} Th
2c530 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2c540 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2c550 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2c560 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
2c570 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
2c580 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2c590 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d  _ERROR] if param
2c5a0 65 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69  eter N (specifyi
2c5b0 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ng the number.**
2c5c0 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67            of arg
2c5d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2c5e0 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  L function being
2c5f0 20 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20   registered) is 
2c600 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
2c610 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2c620 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a  ter than 127..**
2c630 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65  .** {H16127} Whe
2c640 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  n N is non-negat
2c650 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ive, the [sqlite
2c660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c670 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2c680 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2c690 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
2c6a0 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b  acks to be invok
2c6b0 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66  ed for the SQL f
2c6c0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2c6d0 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e      named X when
2c6e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2c6f0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2c700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  SQL function is.
2c710 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63  **          exac
2c720 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tly N..**.** {H1
2c730 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20  6130} When N is 
2c740 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  -1, the [sqlite3
2c750 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c760 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2c770 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2c780 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2c790 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2c7a0 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2c7b0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2c7c0 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20     named X with 
2c7d0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2c7e0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  guments..**.** {
2c7f0 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c  H16133} When cal
2c800 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2c810 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c820 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2c830 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2c840 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2c850 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2c860 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ame function X.*
2c870 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
2c880 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e  hen one implemen
2c890 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20  tation has N>=0 
2c8a0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61  and the other ha
2c8b0 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20  s N=(-1).**     
2c8c0 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65       the impleme
2c8d0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2c8e0 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65  on-zero N is pre
2c8f0 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2c900 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2c910 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2c920 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c930 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2c940 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2c950 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2c960 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2c970 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2c980 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2c990 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2c9a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2c9b0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2c9c0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2c9d0 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2c9e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2c9f0 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2ca00 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2ca10 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2ca20 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72  oding is preferr
2ca30 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2ca40 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67  9} For an aggreg
2ca50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2ca60 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
2ca70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2ca80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ca90 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c  ion(D,X,N,E,P,0,
2caa0 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69  S,L)] the finali
2cab0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
2cac0 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20  function L will 
2cad0 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65  always be invoke
2cae0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69  d exactly once i
2caf0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2cb00 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20    step function 
2cb10 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20  S is called one 
2cb20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2cb30 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68  *.** {H16142} Wh
2cb40 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
2cb50 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
2cb60 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
2cb70 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2cb80 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69      an applicati
2cb90 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2cba0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2cbb0 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  gate created.** 
2cbc0 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
2cbd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cbe0 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  tion()] or [sqli
2cbf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2cc00 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  ion16()],.**    
2cc10 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61        then the a
2cc20 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33  rray of [sqlite3
2cc30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20  _value] objects 
2cc40 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
2cc50 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20            third 
2cc60 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c  parameter are al
2cc70 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20  ways [protected 
2cc80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cc90 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73  bjects..*/.int s
2cca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ccb0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2ccc0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2ccd0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2cce0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2ccf0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2cd00 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2cd10 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2cd20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2cd30 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2cd40 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2cd50 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2cd60 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2cd70 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2cd80 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2cd90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2cda0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2cdb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2cdc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2cdd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2cde0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2cdf0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2ce00 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2ce10 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2ce20 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2ce30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2ce40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2ce50 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2ce60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2ce70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2ce80 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2ce90 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2cea0 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
2ceb0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2cec0 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32   Encodings {H102
2ced0 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31  67} <S50200> <H1
2cee0 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6100>.**.** Thes
2cef0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2cf00 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2cf10 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2cf20 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2cf30 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2cf40 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2cf50 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2cf60 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2cf70 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2cf80 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2cf90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2cfa0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2cfb0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2cfc0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2cfd0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2cfe0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2cff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2d000 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2d010 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2d020 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d030 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2d040 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2d050 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2d060 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d070 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2d080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d090 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2d0a0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2d0b0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2d0c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2d0d0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2d0e0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2d0f0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2d100 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2d110 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2d120 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2d130 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2d140 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2d150 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2d160 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2d170 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2d180 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2d190 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2d1a0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2d1b0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2d1c0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2d1d0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2d1e0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
2d1f0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
2d200 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2d210 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2d220 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
2d230 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2d240 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2d250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
2d260 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2d270 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2d280 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
2d290 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2d2a0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2d2b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
2d2c0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2d2d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
2d2e0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2d2f0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2d300 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2d310 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2d320 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2d330 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2d340 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2d350 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
2d360 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
2d370 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2d380 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2d390 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2d3a0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2d3b0 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2d3c0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2d3d0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2d3e0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2d3f0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2d400 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2d410 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2d420 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2d430 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2d440 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2d450 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2d460 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2d470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d480 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2d490 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d4a0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2d4b0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2d4c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2d4d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2d4e0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2d4f0 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2d500 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2d510 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2d520 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2d530 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2d540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d550 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2d560 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2d570 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2d580 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2d590 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2d5a0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2d5b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2d5c0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2d5d0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2d5e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d5f0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2d600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2d610 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2d620 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d630 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2d640 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2d650 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2d660 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2d670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d680 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2d690 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2d6a0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2d6b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d6c0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
2d6d0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
2d6e0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
2d6f0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
2d700 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
2d710 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
2d720 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
2d730 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d740 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
2d750 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
2d760 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
2d770 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
2d780 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
2d790 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
2d7a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2d7b0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2d7c0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2d7d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2d7e0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2d7f0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2d800 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2d810 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2d820 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2d830 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2d840 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2d850 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2d860 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
2d870 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2d880 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2d890 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2d8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d8b0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2d8c0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2d8d0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2d8e0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2d8f0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2d900 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2d910 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2d920 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2d930 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2d940 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2d950 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2d960 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2d970 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2d980 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2d990 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2d9a0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2d9b0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2d9c0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2d9d0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2d9e0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2d9f0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2da00 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2da10 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2da20 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2da30 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2da40 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2da50 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2da60 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2da70 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2da80 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2da90 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2daa0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2dab0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2dac0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2dad0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2dae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2daf0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2db00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2db10 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2db20 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2db30 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2db40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2db50 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2db60 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2db70 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2db80 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2db90 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2dba0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2dbb0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2dbc0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2dbd0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2dbe0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2dbf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2dc00 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2dc10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2dc20 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
2dc30 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2dc40 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54  **.** {H15103} T
2dc50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2dc60 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2dc70 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2dc80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2dc90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2dca0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2dcb0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2dcc0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2dcd0 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e    returns a poin
2dce0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2dcf0 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2dd00 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b  * {H15106} The [
2dd10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2dd20 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2dd30 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2dd40 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2dd50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2dd60 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2dd70 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2dd80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2dd90 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2dda0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2ddb0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2ddc0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2ddd0 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2dde0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2ddf0 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2de00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2de10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2de20 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  (V)]..**.** {H15
2de30 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2de40 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2de50 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2de60 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2de70 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2de80 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2de90 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2dea0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2deb0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2dec0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2ded0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2dee0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2def0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2df00 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2df10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2df20 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2df30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2df40 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2df50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2df60 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2df70 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65  .** {H15112} The
2df80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2df90 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2dfa0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2dfb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2dfc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2dfd0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2dfe0 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2dff0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2e000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2e010 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2e020 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2e030 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {H15115} The [s
2e040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e050 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2e060 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2e070 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2e080 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e090 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2e0a0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2e0b0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2e0c0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2e0d0 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2e0e0 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2e0f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38  r..**.** {H15118
2e100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2e110 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2e120 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2e130 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2e140 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2e150 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e160 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2e170 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2e180 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2e190 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2e1a0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2e1b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d  ..**.** {H15121}
2e1c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e1d0 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2e1e0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2e1f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e200 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2e210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e220 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2e230 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2e240 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2e250 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2e260 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2e270 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2e280 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H15124} The [sql
2e290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e2a0 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2e2b0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2e2c0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2e2d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e2e0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e2f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e300 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2e310 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2e320 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2e330 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2e340 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2e350 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e360 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2e370 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54  **.** {H15127} T
2e380 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e390 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
2e3a0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2e3b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2e3c0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2e3d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e3e0 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2e3f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2e400 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2e410 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
2e420 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
2e430 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2e440 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e450 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2e460 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d  ..**.** {H15130}
2e470 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e480 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2e490 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e4a0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e4b0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e4d0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2e4e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2e4f0 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2e500 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2e510 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2e520 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2e530 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2e540 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2e550 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2e560 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
2e570 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
2e580 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2e590 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2e5a0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2e5b0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2e5c0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2e5d0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2e5e0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2e5f0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2e600 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2e610 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2e620 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2e630 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
2e640 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20  .**.** {H15136} 
2e650 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2e660 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2e670 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2e680 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
2e690 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
2e6a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e6b0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
2e6c0 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
2e6d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2e6e0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2e6f0 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
2e700 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
2e710 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
2e720 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
2e730 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
2e740 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2e750 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2e760 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2e770 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2e780 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2e790 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
2e7a0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2e7b0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
2e7c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2e7d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e7e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e7f0 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
2e800 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
2e810 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2e820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2e830 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
2e840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2e850 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2e860 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e880 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2e890 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
2e8a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2e8b0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2e8c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2e8d0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2e8e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
2e8f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2e900 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2e910 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2e920 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2e930 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2e940 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2e950 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2e960 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e970 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2e980 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2e990 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2e9a0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2e9b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2e9c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e9d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2e9e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e9f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2ea00 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2ea10 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ea20 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2ea30 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2ea40 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2ea50 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2ea60 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2ea70 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
2ea80 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
2ea90 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
2eaa0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
2eab0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2eac0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
2ead0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
2eae0 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
2eaf0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2eb00 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
2eb10 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
2eb20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2eb30 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
2eb40 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
2eb50 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
2eb60 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
2eb70 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
2eb80 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
2eb90 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
2eba0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
2ebb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2ebc0 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
2ebd0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2ebe0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2ebf0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ec00 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
2ec10 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2ec20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
2ec30 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2ec40 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2ec50 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2ec60 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
2ec70 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
2ec80 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
2ec90 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
2eca0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
2ecb0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2ecc0 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
2ecd0 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
2ece0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
2ecf0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
2ed00 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2ed10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
2ed20 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
2ed30 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
2ed40 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
2ed50 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
2ed60 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
2ed70 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
2ed80 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2ed90 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
2eda0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
2edb0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
2edc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2edd0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2ede0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2edf0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2ee00 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2ee10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2ee20 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2ee30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2ee40 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20  ** {H16211} The 
2ee50 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2ee60 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
2ee70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2ee80 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
2ee90 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
2eea0 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
2eeb0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2eec0 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
2eed0 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
2eee0 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
2eef0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
2ef00 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f  locate N bytes o
2ef10 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20  f memory,.**    
2ef20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20        zero that 
2ef30 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2ef40 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
2ef50 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65  the allocated me
2ef60 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  mory..**.** {H16
2ef70 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79  213} If a memory
2ef80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2ef90 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a  r occurs during.
2efa0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2efb0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2efc0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65  ontext(C,N)] the
2efd0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  n the function r
2efe0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20  eturns 0..**.** 
2eff0 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20  {H16215} Second 
2f000 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69  and subsequent i
2f010 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a  nvocations of.**
2f020 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2f030 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f040 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74  text(C,N)] for t
2f050 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20  he same context 
2f060 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20  pointer C.**    
2f070 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65        ignore the
2f080 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64   N parameter and
2f090 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
2f0a0 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a  r to the same.**
2f0b0 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20            block 
2f0c0 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  of memory return
2f0d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2f0e0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2f0f0 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d  * {H16217} The m
2f100 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
2f110 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  by [sqlite3_aggr
2f120 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2f130 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  N)] is.**       
2f140 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79     automatically
2f150 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65   freed on the ne
2f160 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  xt call to [sqli
2f170 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2f180 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2f190 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f1a0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2f1b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f  ed statement] co
2f1c0 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  ntaining.**     
2f1d0 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61       the aggrega
2f1e0 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  te function asso
2f1f0 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74  ciated with cont
2f200 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ext C..*/.void *
2f210 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f220 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2f230 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2f240 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2f250 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2f260 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2f270 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32  s {H16240} <S202
2f280 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2f290 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f2a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f2b0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2f2c0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2f2d0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2f2e0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2f2f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2f300 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2f310 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f320 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2f330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f340 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2f350 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2f360 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2f370 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2f380 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2f390 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
2f3a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2f3b0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2f3c0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2f3d0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2f3e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2f3f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2f400 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2f410 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2f420 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65  .** {H16243} The
2f430 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2f440 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
2f450 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2f460 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2f470 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
2f480 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2f490 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f4a0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2f4b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2f4c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f4d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2f4e0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
2f4f0 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
2f500 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
2f510 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f520 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f530 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2f540 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ] C..*/.void *sq
2f550 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2f590 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2f5a0 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c  tions {H16250} <
2f5b0 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a  S60600><S20200>.
2f5c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f5d0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2f5e0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2f5f0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2f600 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2f610 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2f620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2f630 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2f640 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2f650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f660 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2f670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f680 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2f690 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2f6a0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2f6b0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2f6c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2f6d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
2f6e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2f6f0 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69  16253} The [sqli
2f700 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f710 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66  andle(C)] interf
2f720 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2f730 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2f740 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20        D pointer 
2f750 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2f760 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f770 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2f780 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2f790 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2f7a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2f7b0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2f7c0 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
2f7d0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
2f7e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f7f0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2f800 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  h [sqlite3_conte
2f810 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65  xt] C..*/.sqlite
2f820 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
2f830 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
2f840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2f850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f860 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
2f870 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30  ary Data {H16270
2f880 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2f890 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2f8a0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2f8b0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2f8c0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2f8d0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2f8e0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2f8f0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2f900 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2f910 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2f920 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2f930 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f940 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2f950 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2f960 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2f970 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2f980 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2f990 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2f9a0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2f9b0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2f9c0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2f9d0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2f9e0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2f9f0 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2fa00 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2fa10 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2fa20 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2fa30 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2fa40 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2fa50 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2fa60 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2fa70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2fa80 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2fa90 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2faa0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2fab0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2fac0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2fad0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2fae0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2faf0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2fb00 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2fb10 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2fb20 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2fb30 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2fb40 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2fb50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2fb60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2fb70 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2fb80 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2fb90 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2fba0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2fbb0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2fbc0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2fbd0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2fbe0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2fbf0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2fc00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fc10 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d  unction. If no m
2fc20 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
2fc30 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
2fc40 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
2fc50 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2fc60 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2fc70 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
2fc80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
2fc90 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
2fca0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2fcb0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
2fcc0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
2fcd0 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
2fce0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2fcf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
2fd00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2fd10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2fd20 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
2fd30 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2fd40 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2fd50 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2fd60 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
2fd70 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
2fd80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fd90 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2fda0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
2fdb0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2fdc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2fdd0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
2fde0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
2fdf0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
2fe00 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20  estroyed..** If 
2fe10 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2fe20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2fe30 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2fe40 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
2fe50 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
2fe60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2fe70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2fe80 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
2fe90 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
2fea0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
2feb0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
2fec0 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
2fed0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2fee0 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
2fef0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
2ff00 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
2ff10 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
2ff20 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
2ff30 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
2ff40 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
2ff50 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
2ff60 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
2ff70 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
2ff80 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
2ff90 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
2ffa0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2ffb0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2ffc0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
2ffd0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  ..**.** In pract
2ffe0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2fff0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
30000 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
30010 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
30020 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
30030 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
30040 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
30050 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
30060 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
30070 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
30080 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30090 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
300a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
300b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
300c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
300d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
300e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
300f0 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68  *.** {H16272} Th
30100 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  e [sqlite3_get_a
30110 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74  uxdata(C,N)] int
30120 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30130 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
30140 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61       to metadata
30150 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30160 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
30170 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
30180 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
30190 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74     whose context
301a0 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69   is C, or NULL i
301b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
301c0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
301d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
301e0 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  th that paramete
301f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34  r..**.** {H16274
30200 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
30210 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
30220 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  ,D)] interface a
30230 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74  ssigns a metadat
30240 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
30250 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e  inter P to the N
30260 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
30270 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30280 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e   with context C.
30290 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20  .**.** {H16276} 
302a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
302b0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
302c0 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
302d0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  e argument.**   
302e0 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20         which is 
302f0 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69  the metadata poi
30300 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67  nter P following
30310 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
30320 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
30330 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
30340 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74  P,D)] when SQLit
30350 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
30360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
30370 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a   metadata..**.**
30380 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65   {H16277} SQLite
30390 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20   ceases to hold 
303a0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20  metadata for an 
303b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  SQL function par
303c0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
303d0 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75     when the valu
303e0 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65  e of that parame
303f0 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  ter changes..**.
30400 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e  ** {H16278} When
30410 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
30420 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
30430 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
30440 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20  destructor.**   
30450 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64         is called
30460 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d   for any prior m
30470 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
30480 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
30490 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
304a0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20        context C 
304b0 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e  and parameter N.
304c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20  .**.** {H16279} 
304d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c  SQLite will call
304e0 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72   destructors for
304f0 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74   any metadata it
30500 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20   is holding.**  
30510 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72          in a par
30520 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65  ticular [prepare
30530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77  d statement] S w
30540 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  hen either.**   
30550 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
30560 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71  reset(S)] or [sq
30570 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
30580 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f  )] is called..*/
30590 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
305a0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
305b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
305c0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
305d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
305e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
305f0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
30600 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
30610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30620 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
30630 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
30640 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
30650 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30   {H10280} <S3010
30660 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0>.**.** These a
30670 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
30680 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
30690 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
306a0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
306b0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
306c0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
306d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
306e0 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68  _blob()].  If th
306f0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
30700 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
30710 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
30720 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
30730 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
30740 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
30750 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
30760 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
30770 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
30780 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51  oyed.  The.** SQ
30790 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
307a0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
307b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
307c0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
307d0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
307e0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
307f0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
30800 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
30810 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
30820 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
30830 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
30840 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
30850 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
30860 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
30870 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
30880 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
30890 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
308a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
308b0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
308c0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
308d0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
308e0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
308f0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
30900 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
30910 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
30920 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
30930 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30940 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
30950 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
30960 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
30970 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36  QL Function {H16
30980 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  400} <S20200>.**
30990 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
309a0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
309b0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
309c0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
309d0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
309e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
309f0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
30a00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
30a10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
30a20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
30a30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30a40 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
30a50 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
30a60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
30a70 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
30a80 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
30a90 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
30aa0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
30ab0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
30ac0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
30ad0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
30ae0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
30af0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
30b00 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
30b10 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
30b20 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
30b30 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
30b40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
30b50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30b60 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
30b70 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
30b80 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
30b90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30ba0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30bb0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
30bc0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
30bd0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
30be0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
30bf0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
30c00 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
30c10 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
30c20 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
30c30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30c40 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
30c50 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
30c60 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
30c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30c80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30c90 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
30ca0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
30cb0 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
30cc0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
30cd0 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
30ce0 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
30cf0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
30d00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30d10 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
30d20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
30d30 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
30d40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30d50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30d60 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
30d70 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
30d80 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
30d90 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30da0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30db0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
30dc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30dd0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
30de0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
30df0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
30e00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
30e10 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
30e20 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
30e30 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
30e40 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
30e50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
30e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30e70 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
30e80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
30e90 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
30ea0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
30eb0 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69  ssage.  SQLite i
30ec0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
30ed0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
30ee0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30ef0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30f00 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69  ) as UTF-8. SQLi
30f10 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
30f20 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
30f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30f40 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
30f50 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
30f60 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66   byte order.  If
30f70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
30f80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30f90 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
30fa0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
30fb0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
30fc0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
30fd0 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
30fe0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
30ff0 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
31000 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
31010 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
31020 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72  ..** If the thir
31030 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
31040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31050 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
31060 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31070 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
31080 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
31090 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
310a0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
310b0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
310c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
310d0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
310e0 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73  essage..** The s
310f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31100 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
31110 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31120 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
31130 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
31140 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
31150 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
31160 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
31170 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
31180 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
31190 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
311a0 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
311b0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
311c0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
311d0 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  harm..** The sql
311e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
311f0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
31200 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
31210 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
31220 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
31230 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
31240 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
31250 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c  tion.  By defaul
31260 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
31270 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
31280 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75  RROR.  A subsequ
31290 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
312a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
312b0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
312c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
312d0 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
312e0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
312f0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54  E_ERROR..**.** T
31300 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31310 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  t_toobig() inter
31320 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
31330 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
31340 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
31350 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
31360 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c   or BLOB is to l
31370 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
31380 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
31390 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
313a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
313b0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
313c0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
313d0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
313e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
313f0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
31400 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31410 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
31420 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31430 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31450 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31460 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
31470 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
31480 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
31490 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
314a0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ment..** The sql
314b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
314c0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
314d0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
314e0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
314f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31500 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31510 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
31520 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
31530 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
31540 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
31550 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31560 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
31570 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31580 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31590 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
315a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
315b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
315c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
315d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
315e0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
315f0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
31600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31610 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
31620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31630 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
31640 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
31650 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
31660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31670 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31680 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
31690 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
316a0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
316b0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
316c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
316d0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
316e0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
316f0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
31700 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53  spectively..** S
31710 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
31720 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
31730 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31740 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
31750 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
31760 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31770 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31780 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  s..** If the 3rd
31790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
317a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
317b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
317c0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
317d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
317e0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
317f0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
31800 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
31810 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
31820 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
31830 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31840 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31850 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31860 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31870 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31880 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
31890 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
318a0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
318b0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
318c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
318d0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
318e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
318f0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
31900 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
31910 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31920 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
31930 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31940 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
31950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
31960 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
31970 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
31980 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
31990 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
319a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
319b0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
319c0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
319d0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
319e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
319f0 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
31a00 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
31a10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31a20 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31a30 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  aces or.** sqlit
31a40 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
31a50 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
31a60 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
31a70 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
31a80 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
31a90 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
31aa0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
31ab0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
31ac0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
31ad0 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61  opy the it or ca
31ae0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
31af0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
31b00 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
31b10 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
31b20 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
31b30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31b40 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31b50 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
31b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31b70 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
31b80 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
31b90 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
31ba0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
31bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
31bc0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
31bd0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
31be0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
31bf0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
31c00 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
31c10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31c20 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
31c30 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31c40 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
31c50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31c60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31c70 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
31c80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
31c90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31ca0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
31cb0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31cc0 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
31cd0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31ce0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
31cf0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
31d00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31d10 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
31d20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
31d30 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
31d40 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
31d50 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
31d60 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
31d70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31d80 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
31d90 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
31da0 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
31db0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31dc0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
31dd0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
31de0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31e00 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
31e10 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
31e20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
31e30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
31e40 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
31e50 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
31e60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
31e70 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
31e80 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
31e90 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
31ea0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
31eb0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
31ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ed0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31ee0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
31ef0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
31f00 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
31f10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
31f20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31f30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31f40 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20  ** {H16403} The 
31f50 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76  default return v
31f60 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51  alue from any SQ
31f70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55  L function is NU
31f80 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30  LL..**.** {H1640
31f90 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
31fa0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
31fb0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
31fc0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
31fd0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
31fe0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
31ff0 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20   C to be a BLOB 
32000 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a  that is N bytes.
32010 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c  **          in l
32020 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63  ength and with c
32030 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74  ontent pointed t
32040 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  o by V..**.** {H
32050 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  16409} The [sqli
32060 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
32070 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
32080 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32090 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
320a0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
320b0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66  on C to be the f
320c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
320d0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lue V..**.** {H1
320e0 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6412} The [sqlit
320f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32100 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
32110 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
32120 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
32130 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32140 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
32150 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
32160 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
32170 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
32180 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65  R] and a UTF-8 e
32190 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70  rror message cop
321a0 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
321b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
321c0 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65   first zero byte
321d0 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
321e0 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20  s are read if N 
321f0 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
32200 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20  ** {H16415} The 
32210 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32220 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20  error16(C,V,N)] 
32230 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32240 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
32250 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
32260 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32270 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
32280 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
32290 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
322a0 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
322b0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
322c0 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20  yte order error 
322d0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
322e0 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20      copied from 
322f0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
32300 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
32310 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  r or until N byt
32320 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
32330 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20  re read if N is 
32340 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
32350 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71  {H16418} The [sq
32360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32370 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e  or_toobig(C)] in
32380 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32390 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
323a0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
323b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
323c0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
323d0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
323e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
323f0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e  QLITE_TOOBIG] an
32400 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
32410 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
32420 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54  **.** {H16421} T
32430 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32440 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43  lt_error_nomem(C
32450 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32460 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
32470 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
32480 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32490 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
324a0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
324b0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
324c0 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d     [SQLITE_NOMEM
324d0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
324e0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
324f0 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
32500 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
32510 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32520 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63  e(C,E)] interfac
32530 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
32540 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
32550 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
32560 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
32570 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
32580 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a   error code E..*
32590 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65  *          The e
325a0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
325b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
325c0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54  **.** {H16427} T
325d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
325e0 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74  lt_int(C,V)] int
325f0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32600 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32610 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32620 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32630 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67  the 32-bit integ
32640 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
32650 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b  * {H16430} The [
32660 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
32670 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72  nt64(C,V)] inter
32680 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
326a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
326b0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
326c0 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  e 64-bit integer
326d0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
326e0 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71  {H16433} The [sq
326f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
32700 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  l(C)] interface 
32710 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32720 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32730 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32740 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a   C to be NULL..*
32750 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68  *.** {H16436} Th
32760 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32770 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
32780 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32790 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
327a0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
327b0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
327c0 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74   be the UTF-8 st
327d0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
327e0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
327f0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
32800 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
32810 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
32820 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
32830 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
32840 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
32850 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  39} The [sqlite3
32860 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
32870 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
32880 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
32890 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
328a0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
328b0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
328c0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
328d0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
328e0 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
328f0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
32900 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
32910 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
32920 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
32930 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
32940 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
32950 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54  **.** {H16442} T
32960 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32970 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
32980 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
32990 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
329a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
329b0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
329c0 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
329d0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
329e0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
329f0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
32a00 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
32a10 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
32a20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
32a30 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20  st N bytes or V 
32a40 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
32a50 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
32a60 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  445} The [sqlite
32a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
32a80 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
32a90 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32aa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
32ab0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
32ac0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
32ad0 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  he UTF-16 little
32ae0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
32af0 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
32b00 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
32b10 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
32b20 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
32b30 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
32b40 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
32b50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
32b60 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68  *.** {H16448} Th
32b70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32b80 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e  t_value(C,V)] in
32b90 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32ba0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32bb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32bc0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32bd0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
32be0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a  .**          obj
32c00 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
32c10 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6451} The [sqlit
32c20 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
32c30 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(C,N)] interfa
32c40 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
32c50 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32c60 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
32c70 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e  ion C to be an N
32c80 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c  -byte BLOB of al
32c90 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b  l zeros..**.** {
32ca0 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c  H16454} The [sql
32cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32cc0 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  r()] and [sqlite
32cd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32ce0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
32cf0 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20  interfaces make 
32d00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20  a copy of their 
32d10 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
32d20 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20  rings before.** 
32d30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69           returni
32d40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35  ng..**.** {H1645
32d50 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  7} If the D dest
32d60 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
32d70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
32d80 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
32d90 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32da0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32db0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
32dc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32dd0 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
32de0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
32df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32e00 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
32e10 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
32e20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32e30 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
32e40 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74  D)] is the const
32e50 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
32e60 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  IC].**          
32e70 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74  then no destruct
32e80 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65  or is ever calle
32e90 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72  d on the pointer
32ea0 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a   V and SQLite.**
32eb0 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65            assume
32ec0 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75  s that V is immu
32ed0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  table..**.** {H1
32ee0 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64  6460} If the D d
32ef0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
32f00 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
32f10 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
32f20 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
32f30 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32f40 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
32f50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
32f60 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
32f70 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
32f80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32f90 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
32fa0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
32fb0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32fc0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
32fd0 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f  ,N,D)] is the co
32fe0 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20  nstant.**       
32ff0 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53     [SQLITE_TRANS
33000 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69  IENT] then the i
33010 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20  nterfaces makes 
33020 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
33030 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e            conten
33040 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69  t of V and retai
33050 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a  ns the copy..**.
33060 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74  ** {H16463} If t
33070 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
33080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
33090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
330a0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
330b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
330c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
330d0 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
330e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
330f0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
33100 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33110 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
33120 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
33130 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
33140 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33150 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
33160 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72  some value other
33170 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
33180 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20    the constants 
33190 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20  [SQLITE_STATIC] 
331a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  and [SQLITE_TRAN
331b0 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20  SIENT] then.**  
331c0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77          SQLite w
331d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
331e0 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
331f0 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61   V as its only a
33200 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  rgument.**      
33210 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20      when it has 
33220 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
33230 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f  e V value..*/.vo
33240 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33250 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
33260 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33270 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
33280 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
33290 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
332a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
332b0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
332c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
332d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
332e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
332f0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
33300 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33310 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
33320 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33330 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
33340 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33350 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
33360 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
33370 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
33380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33390 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
333a0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
333b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
333c0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
333d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
333e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
333f0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
33400 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
33410 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33420 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
33430 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
33440 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
33450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33460 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
33470 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
33480 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
334a0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
334b0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
334c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
334d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
334e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
334f0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33500 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
33510 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
33520 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33530 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
33540 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33550 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
33560 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33570 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33580 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
33590 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
335a0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
335b0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
335c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
335d0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
335e0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
335f0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
33600 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
33610 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
33620 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
33630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
33640 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
33650 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
33660 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
33670 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
33680 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
33690 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
336a0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
336b0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
336c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
336d0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
336e0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
336f0 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
33700 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
33710 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
33720 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
33730 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
33740 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33750 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
33760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33770 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
33780 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
33790 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
337a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
337b0 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
337c0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
337d0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
337e0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
337f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33800 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
33810 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
33820 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
33830 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
33840 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
33850 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  ] or [SQLITE_UTF
33860 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
33870 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
33880 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
33890 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
338a0 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
338b0 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
338c0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
338d0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
338e0 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
338f0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
33900 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54   respectively. T
33910 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
33920 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
33930 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
33940 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64  _ALIGNED] to ind
33950 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68  icate that.** th
33960 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
33970 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
33980 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
33990 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
339a0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
339b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
339c0 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  of the host comp
339d0 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  uter..**.** A po
339e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
339f0 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
33a00 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
33a10 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
33a20 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
33a30 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
33a40 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
33a50 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
33a60 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
33a70 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
33a80 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
33a90 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45  t anymore)..** E
33aa0 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70  ach time the app
33ab0 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65  lication supplie
33ac0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  d function is in
33ad0 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73  voked, it is pas
33ae0 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69  sed.** as its fi
33af0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20  rst parameter a 
33b00 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
33b10 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
33b20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
33b30 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ** to sqlite3_cr
33b40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33b50 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
33b60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61  ..**.** The rema
33b80 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
33b90 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
33ba0 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
33bb0 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
33bc0 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
33bd0 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
33be0 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
33bf0 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
33c00 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
33c10 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
33c20 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
33c30 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
33c40 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33c50 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
33c60 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ered. {END}  The
33c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33c80 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
33c90 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
33ca0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
33cb0 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
33cc0 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ve if the first 
33cd0 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
33ce0 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f  han,.** equal to
33cf0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
33d00 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72  n the second str
33d10 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
33d20 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
33d30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33d40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33d50 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
33d60 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
33d70 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
33d80 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
33d90 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
33da0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
33db0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
33dc0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
33dd0 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
33de0 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
33df0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
33e00 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
33e10 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
33e20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
33e30 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
33e40 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
33e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
33e60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33e70 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
33e80 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
33e90 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
33ea0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
33eb0 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  r calls to the.*
33ec0 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  * collation crea
33ed0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
33ee0 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61  r when the [data
33ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33f00 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73   is closed.** us
33f10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
33f20 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  se()]..**.** INV
33f30 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
33f40 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73  H16603} A succes
33f50 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65  sful call to the
33f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33f80 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
33f90 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  P,F,D)] interfac
33fa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
33fb0 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e  gisters function
33fc0 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72   F as the compar
33fd0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73  ison function us
33fe0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
33ff0 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c    implement coll
34000 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b  ation X on the [
34010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34020 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20  ion] B for.**   
34030 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73         databases
34040 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67   having encoding
34050 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30   E..**.** {H1660
34060 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73  4} SQLite unders
34070 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61  tands the X para
34080 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
34090 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
340a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
340b0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
340c0 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
340d0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
340e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
340f0 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69   which case is i
34100 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49  gnored for ASCII
34110 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a   characters and.
34120 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73  **          is s
34130 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e  ignificant for n
34140 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74  on-ASCII charact
34150 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ers..**.** {H166
34160 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63  06} Successive c
34170 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34180 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34190 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
341a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
341b0 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ith the same val
341c0 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e  ues for B, X, an
341d0 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72  d E, override pr
341e0 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  ior values.**   
341f0 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20         of P, F, 
34200 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and D..**.** {H1
34210 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73  6609} If the des
34220 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71  tructor D in [sq
34230 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34240 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
34250 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
34260 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20      is not NULL 
34270 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65  then it is calle
34280 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
34290 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  P when the.**   
342a0 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
342b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
342c0 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  pped by SQLite..
342d0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41  **.** {H16612} A
342e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
342f0 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
34300 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f  hen it is overlo
34310 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  aded..**.** {H16
34320 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  615} A collating
34330 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
34340 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61  pped when the da
34350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34360 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
34370 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
34380 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
34390 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20  .**.** {H16618} 
343a0 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e  The pointer P in
343b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
343c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
343d0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
343e0 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65          is passe
343f0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
34400 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
34410 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73   to the comparis
34420 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  on.**          f
34430 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
34440 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
34450 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a  ocations of F..*
34460 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20  *.** {H16621} A 
34470 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34480 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34490 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73  n(B,X,E,P,F)] is
344a0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
344b0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
344c0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
344d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
344e0 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a  tion_v2()] with.
344f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
34500 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20  same parameters 
34510 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72  and a NULL destr
34520 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  uctor..**.** {H1
34530 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20  6624} Following 
34540 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  a [sqlite3_creat
34550 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
34560 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a  ,X,E,P,F,D)],.**
34570 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
34580 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72   uses the compar
34590 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20  ison function F 
345a0 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d  for all text com
345b0 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20  parison.**      
345c0 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f      operations o
345d0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
345e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e  connection] B on
345f0 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61   text values tha
34600 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  t.**          us
34610 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  e the collating 
34620 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58  sequence named X
34630 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d  ..**.** {H16627}
34640 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
34650 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
34660 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72  (B,X,E,P,F)] wor
34670 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  ks the same.**  
34680 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69          as [sqli
34690 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
346a0 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  tion(B,X,E,P,F)]
346b0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
346c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
346d0 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  lation name X is
346e0 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55   understood as U
346f0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
34700 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
34710 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f         instead o
34720 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  f UTF-8..**.** {
34730 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c  H16630} When mul
34740 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e  tiple comparison
34750 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
34760 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65  vailable for the
34770 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
34780 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75    collating sequ
34790 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f  ence, SQLite cho
347a0 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f  oses the one who
347b0 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  se text encoding
347c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71  .**          req
347d0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
347e0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72  amount of conver
347f0 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65  sion from the de
34800 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20  fault.**        
34810 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20    text encoding 
34820 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  of the database.
34830 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34840 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34850 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34860 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34870 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
34880 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
34890 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
348a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
348b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
348c0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
348d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
348e0 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
348f0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
34900 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
34910 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
34920 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
34930 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
34940 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
34950 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
34960 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
34970 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
34980 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34990 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
349a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
349b0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
349c0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
349d0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
349e0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
349f0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
34a00 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
34a10 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34a20 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
34a30 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
34a40 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
34a50 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
34a60 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
34a70 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
34a80 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
34a90 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
34aa0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
34ab0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
34ac0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
34ad0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
34ae0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
34af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
34b00 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
34b10 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
34b20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
34b30 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
34b40 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
34b50 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
34b60 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
34b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34b80 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
34b90 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
34ba0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
34bb0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
34bc0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
34bd0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
34be0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
34bf0 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
34c00 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34c10 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
34c20 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
34c30 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
34c40 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
34c50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34c60 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
34c70 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
34c80 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
34c90 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
34ca0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
34cb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34cc0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
34cd0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
34ce0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
34cf0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
34d00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
34d10 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
34d20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
34d30 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
34d40 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
34d50 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
34d60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
34d70 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
34d80 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
34d90 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
34da0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
34db0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
34dc0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
34dd0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
34de0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
34df0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
34e00 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
34e10 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
34e20 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
34e30 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
34e40 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
34e50 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
34e60 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
34e70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
34e80 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
34e90 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
34ea0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
34eb0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
34ec0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34ed0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
34ee0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34ef0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
34f00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34f10 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
34f20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
34f30 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75  ** {H16702} A su
34f40 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
34f50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34f60 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46  ion_needed(D,P,F
34f70 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
34f80 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  r [sqlite3_colla
34f90 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c  tion_needed16(D,
34fa0 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20  P,F)] causes.** 
34fb0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
34fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34fd0 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63  n] D to invoke c
34fe0 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66  allback F with f
34ff0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
35000 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
35010 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61  never it needs a
35020 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
35030 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20  tion for a.**   
35040 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
35050 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69   sequence that i
35060 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20  t does not know 
35070 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  about..**.** {H1
35080 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65  6704} Each succe
35090 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
350a0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
350b0 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a  _needed()] or.**
350c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
350d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
350e0 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64  ded16()] overrid
350f0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  es the callback 
35100 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
35110 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
35120 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
35130 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f  nection] by prio
35140 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65  r calls to eithe
35150 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
35160 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
35170 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65  H16706} The name
35180 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65   of the requeste
35190 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  d collating func
351a0 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74  tion passed in t
351b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34  he.**          4
351c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
351d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
351e0 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20  in UTF-8 if the 
351f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
35200 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65       was registe
35210 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
35220 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35230 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ded()] and.**   
35240 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46         is in UTF
35250 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
35260 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c  order if the cal
35270 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20  lback was.**    
35280 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
35290 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
352a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
352b0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
352c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
352d0 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
352e0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
352f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
35300 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
35310 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
35320 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
35330 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35340 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
35350 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
35360 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
35370 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
35380 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35390 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
353a0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
353b0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
353c0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
353d0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
353e0 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
353f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
35400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
35410 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
35420 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
35430 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
35440 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
35450 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
35460 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
35470 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35490 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
354a0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
354b0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
354c0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
354d0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
354e0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
354f0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
35500 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
35510 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
35520 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
35530 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
35540 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
35550 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
35560 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
35570 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
35580 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
35590 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
355a0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
355b0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
355c0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
355d0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
355e0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
355f0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
35600 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35610 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35620 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35630 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35640 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35650 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
35660 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
35670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35680 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
35690 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
356a0 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34  ime {H10530} <S4
356b0 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0410>.**.** The 
356c0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
356d0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
356e0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
356f0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
35700 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
35710 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
35720 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35730 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
35740 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
35750 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
35760 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
35770 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
35780 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
35790 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
357a0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
357b0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
357c0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
357d0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
357e0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
357f0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35800 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
35810 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
35820 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
35830 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
35840 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
35850 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
35860 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
35870 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
35880 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
35890 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
358a0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
358b0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
358c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
358d0 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b  * {H10533} The [
358e0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29  sqlite3_sleep(M)
358f0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f  ] interface invo
35900 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a  kes the xSleep.*
35910 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f  *          metho
35920 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
35930 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46   [sqlite3_vfs|VF
35940 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  S] in order to.*
35950 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65  *          suspe
35960 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  nd execution of 
35970 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35980 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a  ad for at least.
35990 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69  **          M mi
359a0 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a  lliseconds..**.*
359b0 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b  * {H10536} The [
359c0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29  sqlite3_sleep(M)
359d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
359e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
359f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69  f.**          mi
35a00 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
35a10 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71  eep actually req
35a20 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70  uested of the op
35a30 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20  erating.**      
35a40 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63      system, whic
35a50 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  h might be large
35a60 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d  r than the param
35a70 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73  eter M..*/.int s
35a80 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
35a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35aa0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
35ab0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
35ac0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
35ad0 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e  H10310} <S20000>
35ae0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67  .**.** If this g
35af0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35b00 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
35b10 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
35b20 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
35b30 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
35b40 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
35b50 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
35b60 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
35b70 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
35b80 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
35b90 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
35ba0 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62    If this variab
35bb0 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
35bc0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
35bd0 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
35be0 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
35bf0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
35c00 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
35c10 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
35c20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
35c30 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35c40 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61  ble once a [data
35c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35c60 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65  .** has been ope
35c70 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65  ned.  It is inte
35c80 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
35c90 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
35ca0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
35cb0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
35cc0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
35cd0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
35ce0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
35cf0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
35d00 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75  all and remain u
35d10 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66  nchanged thereaf
35d20 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ter..*/.SQLITE_E
35d30 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
35d40 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
35d50 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
35d60 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
35d70 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
35d80 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e  H12930} <S60200>
35d90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
35da0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
35db0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35dc0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
35dd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35de0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
35df0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
35e00 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
35e10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
35e20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
35e30 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
35e40 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74  spectively.  Aut
35e50 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35e60 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
35e70 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
35e80 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
35e90 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
35ea0 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
35eb0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
35ec0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
35ed0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
35ee0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
35ef0 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
35f00 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
35f10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
35f20 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
35f30 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
35f40 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
35f50 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
35f60 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
35f70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
35f80 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
35f90 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
35fa0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
35fb0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
35fc0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
35fd0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
35fe0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
35ff0 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
36000 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
36010 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
36020 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
36030 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
36040 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
36050 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
36060 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
36070 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
36080 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65 20 5b  * {H12931} The [
36090 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
360a0 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72  commit(D)] inter
360b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
360c0 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20  -zero or.**     
360d0 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65       zero if the
360e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
360f0 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69  ction] D is or i
36100 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
36110 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mit.**          
36120 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65  mode, respective
36130 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  ly..**.** {H1293
36140 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  2} Autocommit mo
36150 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
36160 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ult..**.** {H129
36170 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  33} Autocommit m
36180 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
36190 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
361a0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
361b0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 34  t..**.** {H12934
361c0 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
361d0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20  e is enabled by 
361e0 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f  a successful [CO
361f0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
36200 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  CK].**          
36210 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
36220 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
36230 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 20  .** {A12936} If 
36240 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
36250 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
36260 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
36270 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36280 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74           connect
36290 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
362a0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
362b0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
362c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  rn value.**     
362d0 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65       is undefine
362e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
362f0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
36300 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
36310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
36320 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
36330 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
36340 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
36350 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a  13120} <S60600>.
36360 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36370 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
36380 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
36390 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
363a0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
363b0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
363c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
363d0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20  ] belongs.  The 
363e0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
363f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73  returned by.** s
36400 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
36410 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74   is the same dat
36420 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61  abase handle tha
36430 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
36440 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
36450 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
36460 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
36470 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
36480 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
36490 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
364a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
364b0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
364c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
364d0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54  **.** {H13123} T
364e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
364f0 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
36500 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
36510 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
36520 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
36530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
36540 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
36550 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
36560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36570 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65  nt] S..*/.sqlite
36580 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
36590 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
365a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
365b0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
365c0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
365d0 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20  tement {H13140} 
365e0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
365f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
36600 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36610 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
36620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36630 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
36640 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
36650 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36660 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
36670 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
36680 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
36690 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
366a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
366b0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
366c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
366d0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
366e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
366f0 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f  tion pDb.  If no
36700 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36710 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
36720 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
36730 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
36740 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
36750 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
36760 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34  TS:.**.** {H1314
36770 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  3} If D is a [da
36780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36790 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e  n] that holds on
367a0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
367b0 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65        unfinalize
367c0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
367d0 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73  ements] and S is
367e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
367f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
36800 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
36810 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
36820 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
36830 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
36840 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66         to one of
36850 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
36860 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
36870 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a  ted with D..**.*
36880 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20 44 20  * {H13146} If D 
36890 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
368a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
368b0 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e 61 6c  holds no unfinal
368c0 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ized.**         
368d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
368e0 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20  ments] and S is 
368f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
36900 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
36910 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
36920 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
36930 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
36940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36950 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d 20 49  **.** {H13149} I
36960 66 20 53 20 69 73 20 61 20 5b 70 72 65 70 61 72  f S is a [prepar
36970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
36980 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36990 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
369a0 20 20 20 20 20 20 20 20 20 61 6e 64 20 53 20 69           and S i
369b0 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 70  s not the last p
369c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
369d0 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a 2a 20  t in D, then.** 
369e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
369f0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
36a00 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
36a10 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
36a20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
36a30 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
36a40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ed statement in 
36a50 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a  D after S..**.**
36a60 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53 20 69   {H13152} If S i
36a70 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70  s the last [prep
36a80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36a90 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
36aa0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
36ab0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65 6e 20  nection] D then 
36ac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  the [sqlite3_nex
36ad0 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a  t_stmt(D, S)].**
36ae0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
36af0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
36b00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36b10 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
36b20 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35 34 7d  :.**.** {A13154}
36b30 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
36b40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
36b50 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
36b60 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
36b70 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
36b80 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
36b90 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
36ba0 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
36bb0 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64    connection and
36bc0 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
36bd0 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
36be0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
36bf0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
36c00 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
36c10 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
36c20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36c30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36c40 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
36c50 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
36c60 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
36c70 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12950} <S60400>.
36c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36c90 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
36ca0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36cb0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
36cc0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
36cd0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36ce0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
36cf0 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
36d00 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
36d10 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
36d20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36d30 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
36d40 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
36d50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36d60 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36d70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36d80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
36d90 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
36da0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
36db0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
36dc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36dd0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
36de0 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
36df0 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
36e00 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
36e10 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36e20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
36e30 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
36e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36e50 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36e60 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
36e70 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
36e80 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
36e90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74  allback..** If t
36ea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
36eb0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
36ec0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
36ed0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
36ee0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
36ef0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
36f00 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
36f10 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
36f20 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
36f30 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
36f40 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
36f50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
36f60 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
36f70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
36f80 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
36f90 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
36fa0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
36fb0 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
36fc0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
36fd0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
36fe0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
36ff0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
37000 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
37010 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
37020 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
37030 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
37040 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
37050 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
37060 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
37070 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
37080 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
37090 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
370a0 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
370b0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
370c0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
370d0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
370e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
370f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
37100 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
37110 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
37120 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
37130 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
37140 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
37150 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c  use a commit cal
37160 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e  lback returned n
37170 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64  on-zero..** <tod
37180 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73  o> Check on this
37190 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49   </todo>.**.** I
371a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
371b0 20 7b 48 31 32 39 35 31 7d 20 54 68 65 20 5b 73   {H12951} The [s
371c0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
371d0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
371e0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74  face registers t
371f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
37200 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37210 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
37220 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
37230 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
37240 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74        a transact
37250 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74  ion commits on t
37260 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37270 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
37280 2a 20 7b 48 31 32 39 35 32 7d 20 54 68 65 20 5b  * {H12952} The [
37290 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
372a0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
372b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
372c0 65 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  e P argument.** 
372d0 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68           from th
372e0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
372f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 5b 64  with the same [d
37300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37310 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
37320 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68     or NULL on th
37330 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72  e first call for
37340 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
37350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37360 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  n D..**.** {H129
37370 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  53} Each call to
37380 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
37390 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
373a0 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
373b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
373c0 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
373d0 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   calls..**.** {H
373e0 31 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20  12954} If the F 
373f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
37400 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
37410 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c  (D,F,P)] is NULL
37420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37430 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
37440 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
37450 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
37460 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
37470 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
37480 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
37490 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20   commits..**.** 
374a0 7b 48 31 32 39 35 35 7d 20 49 66 20 74 68 65 20  {H12955} If the 
374b0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
374c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
374d0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
374e0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
374f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
37500 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
37510 20 7b 48 31 32 39 36 31 7d 20 54 68 65 20 5b 73   {H12961} The [s
37520 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37530 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
37540 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37550 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37560 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
37570 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
37580 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
37590 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
375a0 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
375b0 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
375c0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
375d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
375e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20  .**.** {H12962} 
375f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
37600 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
37610 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
37620 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20  urns the P.**   
37630 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
37640 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
37650 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
37660 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
37670 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37680 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
37690 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
376a0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
376b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
376c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
376d0 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
376e0 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c  12963} Each call
376f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
37700 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76  lback_hook()] ov
37710 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
37720 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
37730 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
37740 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
37750 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49 66 20 74  ** {H12964} If t
37760 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
37770 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
37780 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
37790 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
377a0 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c      then the rol
377b0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
377c0 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20  ack is canceled 
377d0 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
377e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
377f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
37800 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
37810 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  back..*/.void *s
37820 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37830 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
37840 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
37850 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
37860 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37870 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
37880 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
37890 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
378a0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
378b0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
378c0 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 7d 20  lbacks {H12970} 
378d0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
378e0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
378f0 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
37900 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
37910 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37920 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
37930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37940 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
37950 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37960 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
37970 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37980 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
37990 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
379a0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
379b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
379c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
379d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
379e0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
379f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37a00 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
37a10 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
37a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
37a30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
37a40 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
37a50 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
37a60 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
37a70 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
37a80 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
37a90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
37aa0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
37ab0 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
37ac0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
37ad0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37ae0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
37af0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
37b00 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
37b10 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
37b20 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
37b30 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
37b40 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
37b50 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
37b60 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
37b70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
37b80 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54  be invoked..** T
37b90 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
37ba0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
37bb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
37bc0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
37bd0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
37be0 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
37bf0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
37c00 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
37c10 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
37c20 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
37c30 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
37c40 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61  e row. In the ca
37c50 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61  se of.** an upda
37c60 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
37c70 72 6f 77 69 64 20 61 66 74 65 72 20 74 68 65 20  rowid after the 
37c80 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
37c90 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
37ca0 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
37cb0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
37cc0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
37cd0 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
37ce0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
37cf0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
37d00 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
37d10 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
37d20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
37d30 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
37d40 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
37d50 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
37d60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
37d70 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
37d80 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
37d90 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 31 7d  :.**.** {H12971}
37da0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   The [sqlite3_up
37db0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
37dc0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ] interface caus
37dd0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
37de0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
37df0 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
37e00 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20  oked with first 
37e10 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
37e20 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
37e30 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20   a table row is 
37e40 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
37e50 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f  ed, or deleted o
37e60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
37e70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37e80 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
37e90 20 7b 48 31 32 39 37 33 7d 20 54 68 65 20 5b 73   {H12973} The [s
37ea0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37eb0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
37ec0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
37ed0 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
37ee0 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20     of P for the 
37ef0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e  previous call on
37f00 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37f20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
37f30 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66  r NULL for the f
37f40 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  irst call..**.**
37f50 20 7b 48 31 32 39 37 35 7d 20 49 66 20 74 68 65   {H12975} If the
37f60 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
37f70 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69  lback F in [sqli
37f80 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37f90 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20  D,F,P)].**      
37fa0 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e      is NULL then
37fb0 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63   the no update c
37fc0 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64  allbacks are mad
37fd0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 37  e..**.** {H12977
37fe0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
37ff0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
38000 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72  ook(D,F,P)] over
38010 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c  rides prior call
38020 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
38030 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66   the same interf
38040 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ace on the same 
38050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38060 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
38070 48 31 32 39 37 39 7d 20 54 68 65 20 75 70 64 61  H12979} The upda
38080 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
38090 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
380a0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
380b0 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  stem.**         
380c0 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73 20   tables such as 
380d0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
380e0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
380f0 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a  e are modified..
38100 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31 7d 20 54  **.** {H12981} T
38110 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
38120 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61 74  ter to the updat
38130 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
38140 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66         is one of
38150 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
38160 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
38170 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  ] or [SQLITE_UPD
38180 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ATE],.**        
38190 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74    depending on t
381a0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
381b0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
381c0 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
381d0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
381e0 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e  83} The third an
381f0 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
38200 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
38210 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
38220 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
38230 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
38240 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
38250 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20 6e   which are the n
38260 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20  ames of the.**  
38270 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
38280 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20   and table that 
38290 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64  is being updated
382a0 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35 7d 20 54  ...** {H12985} T
382b0 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
382c0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
382d0 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
382e0 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20  row after.**    
382f0 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67 65        the change
38300 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64   occurs..*/.void
38310 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   *sqlite3_update
38320 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33  _hook(.  sqlite3
38330 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
38340 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63  id *,int ,char c
38350 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73  onst *,char cons
38360 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  t *,sqlite3_int6
38370 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a  4),.  void*.);..
38380 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38390 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
383a0 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
383b0 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53  ache {H10330} <S
383c0 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  30900>.** KEYWOR
383d0 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
383e0 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  e} {shared cache
383f0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   mode}.**.** Thi
38400 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
38410 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
38420 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
38430 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
38440 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
38450 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
38460 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20  tween [database 
38470 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e  connection | con
38480 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20  nections].** to 
38490 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
384a0 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  e. Sharing is en
384b0 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
384c0 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a  ument is true.**
384d0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
384e0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
384f0 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61   false..**.** Ca
38500 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
38510 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
38520 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
38530 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d  e process. {END}
38540 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
38550 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
38560 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
38570 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
38580 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
38590 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
385a0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
385b0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
385c0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
385d0 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
385e0 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
385f0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
38600 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
38610 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
38620 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
38630 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
38640 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
38650 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
38660 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
38670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38680 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
38690 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
386a0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
386b0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
386c0 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
386d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
386e0 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
386f0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
38700 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57  shared cache.  W
38710 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
38720 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
38730 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
38740 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
38750 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
38760 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
38770 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
38780 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
38790 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
387a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
387b0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
387c0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
387d0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
387e0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
387f0 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
38800 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
38810 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
38820 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
38830 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
38840 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
38850 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
38860 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
38870 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
38880 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
38890 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
388a0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
388b0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
388c0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
388d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
388e0 0a 2a 2a 20 7b 48 31 30